On Tuesday 03 October 2017 15:50:17 Konrad Windszus wrote: > I think we also once discussed on the mailing list where to put bundle > documentation: either in the readme or in the site itself. Unfortunately I > couldn't find the according thread. Please help me with the link if you > have it handy. > > Right now the information is a bit distributed and most of the readme's only > contained a minimally adjusted template and most of the information from a > consumer's perspective can be found MD pages below > https://sling.apache.org/documentation/bundles.html. How do we want to > proceed in the future? > > # Put the bundle-specific information rather in the readme to make it easier > to adjust together with the code (in one common PR) # Keep maintaining a > dedicated MD page in the site repository (to make it easier to cross-link > to other pages, probably also better from SEO perspective) > > And the other question is how do we properly cross-link from one to the > other. At least for option 1 I would like to put a link in > https://sling.apache.org/documentation/bundles.html to the individual > readme files. Since right now we are updating all readme files I think we > should include this aspect as well.
Besides moving content from READMEs next to reactor/builder POMs I have no plans on spending more time with them (the goal was to have at least a minimal README with a uniform header in each module before splitting up into ~300 Git repos). >From my experience documentation in wikis or other external documents outdates much faster than documentation close to code. Therefore I prefer having a good README or module "site" and only documenting high-level concepts or general stuff in Sling's site (and wiki). Regards, O. > Once we have an agreement we should document that in > https://sling.apache.org/documentation.html. > > Thanks for your opinions > Konrad
