apache / apache/lucene

Create a Markdown based documentation

Open
#11,870 8 comments 4 reactions 0 assignees View on GitHub
type:documentation
Dominant language
Java
Stars
3.6k
Forks
1.4k
Avg merge
2d 11h
Merged PRs (30d)
88

Description

### Description

I think it would be much easier to read and maintain markdown-based documentation, instead of/in addition to the Javadoc one.
This way we would be able to generate sites from it.
This is a pretty big suggestion and change to Apache Lucene, but I think it'll be worth it.
The initial idea is to unify all of the main Javadoc package summaries to one folder in which each Javadoc package summary (e.g. https://lucene.apache.org/core/9_4_0/core/org/apache/lucene/search/package-summary.html#package.description) is a markdown page.
I think this will be much more modern and comfortable.
Javadocs are great, but I don't think it's meant for such heavy and detailed explanations.
In my opinion it will be easier to understand the usage of Lucene from a regular site based documentation instead of from markdown.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the linked Lucene 9.4.0 package-summary pages and how the current Javadoc summaries are organized. Define the scope for converting the main package summaries to Markdown and identify the site-generation path. Done should be an agreed migration plan or implementation covering those summaries and the generated site output.

Written by the indexing model from the issue text.

Assessment

Tech stack
java, markdown
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.