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
