It is in no way duplicate but additional - if someone wants to move that
content to the plugin site documentation, that's fine.
Still, the site deployment requires extra steps and they get easily
forgotten as we can see on our web site. For example for the feature
model plugin, latest published site is 1.2.0 (we are at 1.3.4 already)
And yes, sometimes it was me forgetting to publish it...
And https://sling.apache.org/components/ looks really ugly....which is
where you get to when you click "Maven Plugins" on the nav bar in our site
Carsten
Am 17.06.2020 um 15:44 schrieb Konrad Windszus:
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 <[email protected]> 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 <[email protected]> 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 <[email protected]> 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
[email protected]
--
--
Carsten Ziegeler
Adobe Research Switzerland
[email protected]
--
--
Carsten Ziegeler
Adobe Research Switzerland
[email protected]
