Maintaining all mojos with parameters correctly manually in the README is a lot of overhead (IMHO more than generating the site). This information comes for free from the code! Strongly recommend to remove that duplicate info from the readme and instead start generating the site :-)
The steps are nicely described in https://sling.apache.org/documentation/development/release-management.html#appendix-b-deploy-maven-plugin-documentation-if-applicable- <https://sling.apache.org/documentation/development/release-management.html#appendix-b-deploy-maven-plugin-documentation-if-applicable-> Konrad > On 17. Jun 2020, at 15:41, Carsten Ziegeler <cziege...@apache.org> wrote: > > Releasing the site requires extra steps which easily gets forgotten. > Right now, the majority of the documentation is in the README in git and the > site points to that file > > Carsten > > > Am 17.06.2020 um 15:38 schrieb Konrad Windszus: >> For the maven-plugins let us rely on the generated site (which evaluates >> javadoc and other metainformation already nicely) and allows to use MD for >> additional pages. >> I prefer that for maven-plugins over a big readme as generating the site is >> a no-brainer during the release and has a standard format every developer >> knows. >> Konrad >>> On 17. Jun 2020, at 13:57, Carsten Ziegeler <cziege...@apache.org> wrote: >>> >>> Thanks Bertrand, >>> >>> that definitely works for me - and is inline with my thoughts as well :) >>> >>> Regards >>> Carsten >>> >>> Am 17.06.2020 um 11:00 schrieb Bertrand Delacretaz: >>>> Hi, >>>> On Wed, Jun 17, 2020 at 7:50 AM Carsten Ziegeler <cziege...@apache.org> >>>> wrote: >>>>> ...Now, I don't want to open a big box here and I don't want to block such >>>>> great contributions, but it would be great if we can agree on a single >>>>> place where to document these things... >>>> Given the long history of our more than 300 modules I think it's fair >>>> to admit that having some docs are on the website (mostly for the >>>> older modules) and some in the corresponding Git repositories is fine. >>>> IMO what's important is to make things discoverable - for the new >>>> GraphQL modules for example I just added >>>> https://sling.apache.org/documentation/bundles/graphql-core.html >>>> yesterday to make them discoverable from the website (as a form of >>>> "teaser page" for those modules) but the core docs are in Git, with >>>> links in both directions so nothing gets missed. >>>> On the other hand I added features to the servlet-helpers lately and >>>> that's already documented at >>>> https://sling.apache.org/documentation/bundles/servlet-helpers.html so >>>> I just expanded that page, with links between it and the repository >>>> README to avoid duplication. >>>> For other modules that consist of several or many repositories it can >>>> make sense to have the overview documentation on the website, with the >>>> module-specific details in Git and again strong links between all >>>> parts of the docs. >>>> In summary I suggest: >>>> -Making sure everything is discoverable from https://sling.apache.org >>>> -Using sensible website tags to help navigation and discovery >>>> -For new modules, in general, putting the detailed or module-specific >>>> documentation in the Git repositories >>>> -Using the website for overview/concept documentations when that makes >>>> sense >>>> -Avoiding duplicated information, which might mean restructuring some >>>> existing docs >>>> -And especially making sure the right links are in place so that none >>>> of this gets missed >>>> would that work? >>>> -Bertrand >>> >>> -- >>> -- >>> Carsten Ziegeler >>> Adobe Research Switzerland >>> cziege...@apache.org > > -- > -- > Carsten Ziegeler > Adobe Research Switzerland > cziege...@apache.org
