[
https://issues.apache.org/jira/browse/MINDEXER-142?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel
]
Martin Todorov updated MINDEXER-142:
------------------------------------
Description:
*Task Description*
It would be great to have some proper documentation and not a few cryptic lines
and some Javadocs.
The current official documentation is published
[here|https://maven.apache.org/maven-indexer/] and it contains very little
useful information. Someone who first encounters the project will need to do a
lot of digging around in order to extract the useful information they need
(mostly by poking around the test code, running through a debugger and hoping
to find what they are looking for).
This project has few and very rare contributions (sometimes as bursts of pull
requests which take forever to be reviewed and merged), mainly because people
feel intimidated to try and make improvements on it, hence the very slow pace
of development and low activity.
In my opinion, if it gets some better documentation and, if it's a requirement
to continuously improve the documentation (could be done as a check list item
in a github issue/pull request template), the project will have a better
development pace, as more people will be able to understand it well enough to
make actual changes.
[~cstamas]: Would this be something you could look into as part of the upcoming
{{6.1.0}} release?
*Task List*
Some ideas of things to cover:
* (off) Define key concepts.
* (off) Explain how the indexer works.
* (off) Describe how the index downloading/updating works and what the
acceptable frequencies of downloading are.
* (off) Add code examples (and expand on this with actual explanations).
* (off) Add links to the example code, as the current documentation doesn't
mention that there is such.
* (off) Cover any other important topics that come to mind and might be useful.
was:
# Task Description
It would be great to have some proper documentation and not a few cryptic lines
and some Javadocs.
The current official documentation is published
[here|https://maven.apache.org/maven-indexer/] and it contains very little
useful information. Someone who first encounters the project will need to do a
lot of digging around in order to extract the useful information they need
(mostly by poking around the test code, running through a debugger and hoping
to find what they are looking for).
This project has few and very rare contributions (sometimes as bursts of pull
requests which take forever to be reviewed and merged), mainly because people
feel intimidated to try and make improvements on it, hence the very slow pace
of development and low activity.
In my opinion, if it gets some better documentation and, if it's a requirement
to continuously improve the documentation (could be done as a check list item
in a github issue/pull request template), the project will have a better
development pace, as more people will be able to understand it well enough to
make actual changes.
[~cstamas]: Would this be something you could look into as part of the upcoming
{{6.1.0}} release?
# Task List
Some ideas of things to cover:
* (off) Define key concepts.
* (off) Explain how the indexer works.
* (off) Describe how the index downloading/updating works and what the
acceptable frequencies of downloading are.
* (off) Add code examples (and expand on this with actual explanations).
* (off) Add links to the example code, as the current documentation doesn't
mention that there is such.
* (off) Cover any other important topics that come to mind and might be useful.
> Add proper documentation with real life examples
> ------------------------------------------------
>
> Key: MINDEXER-142
> URL: https://issues.apache.org/jira/browse/MINDEXER-142
> Project: Maven Indexer
> Issue Type: Task
> Reporter: Martin Todorov
> Priority: Major
>
> *Task Description*
> It would be great to have some proper documentation and not a few cryptic
> lines and some Javadocs.
> The current official documentation is published
> [here|https://maven.apache.org/maven-indexer/] and it contains very little
> useful information. Someone who first encounters the project will need to do
> a lot of digging around in order to extract the useful information they need
> (mostly by poking around the test code, running through a debugger and hoping
> to find what they are looking for).
> This project has few and very rare contributions (sometimes as bursts of pull
> requests which take forever to be reviewed and merged), mainly because people
> feel intimidated to try and make improvements on it, hence the very slow pace
> of development and low activity.
> In my opinion, if it gets some better documentation and, if it's a
> requirement to continuously improve the documentation (could be done as a
> check list item in a github issue/pull request template), the project will
> have a better development pace, as more people will be able to understand it
> well enough to make actual changes.
> [~cstamas]: Would this be something you could look into as part of the
> upcoming {{6.1.0}} release?
> *Task List*
> Some ideas of things to cover:
> * (off) Define key concepts.
> * (off) Explain how the indexer works.
> * (off) Describe how the index downloading/updating works and what the
> acceptable frequencies of downloading are.
> * (off) Add code examples (and expand on this with actual explanations).
> * (off) Add links to the example code, as the current documentation doesn't
> mention that there is such.
> * (off) Cover any other important topics that come to mind and might be
> useful.
--
This message was sent by Atlassian Jira
(v8.20.1#820001)
