Let me quickly list the advantages/disadvantages of having a bundle documentation in the readme.md from my point of view:
Advantages: - It allows a PR to contain documentation together with the actual script changes - The documentation could be versioned as well - Easy to find Disadvantages - The markdown syntax supported by Apache CMS is not the same as the one being supported by Github. Crosslinks would be hard to manage. - Unclear when to publish changes from readme.md to the Apache CMS. So what I would propose right now is to keep maintaining the documentation still in the Apache CMS. The readme.md in the according Maven module should only contain a link towards http://sling.apache.org/documentation/bundles/.... That way at least there is no redundancy. Konrad > On 5 Apr 2017, at 11:32, Robert Munteanu <[email protected]> wrote: > > Hi, > > I like the fact that we have a consistent documentation section in our > site. I also like the README.md, it's very much 'in-your-face' for > developers and also for users browsing via Github. > > I was thinking for some time whether we can unify them by storing the > canonical information in Github as README.md files and then copying the > files to the Sling site after each release. > > This can of course be scripted and we can apply some minimal pre- > processing if needed when committed. One issue that I see is that ASF- > specific markup, like the ref generation ( {{ refs.resources.path }} ) > will not make sense when viewed out of context. > > Thoughts? > > Robert
