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
