Hi All, I updated the PR with your feedback. If there is anything else that requires changes, please let me know.
A couple of questions on my end: Would you like me to create a PR that links the Feature Model README back to the main How-To landing page? Are there plans to create an official Sling Feature Model JSON file that will be hosted on the Sling Downloads page (https://sling.apache.org/downloads.cgi <https://sling.apache.org/downloads.cgi>)? Same question for a Feature Archive (Sling .far binary)? Thanks, Gaston Gonzalez Senior Architect | www.headwire.com <http://www.headwire.com/> > On Jun 17, 2020, at 7:11 AM, Carsten Ziegeler <[email protected]> wrote: > > 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]
