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
