[RT] Unifying site documentation with per-module README.md files?

[Robert Munteanu <ro...@apache.org>]

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

Re: [RT] Unifying site documentation with per-module README.md files?

[Konrad Windszus <ko...@gmx.de>]

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 <ro...@apache.org> 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