Create a Markdown based 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
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