Hi Jacques, I would suggest to make a distinction between two types of documentation: 1- short documentation for quick reference 2- long documentation bringing comprehensive explanations, examples, sections, etc.
Taking this distinction into consideration, I would suggest: - definitely the best place for all documentation is in version control (inside OFBiz preferably) - We should limit markdown to a few places where it makes sense. - For longer documentation I would recommend a more powerful option that can be published into multiple formats and has other publishing features (e.g. table of contents). My preference is for DITA being modular which is very nice for technical documentation. Another option is what we have already (DocBook) and there are other solutions out there. I think we discussed them in the past. In fact if we adopt the solutions I'm suggesting above, even the README.md can be generated from them automatically. With DITA one powerful advantage is the ability to reuse content in different documents so you abide with DRY principle. WDYT? Taher Alkhateeb On Aug 20, 2016 8:29 AM, "[email protected]" <[email protected]> wrote: > Hi, > > Not so long ago Jacopo suggested that we use our versionning system (ie > currently Subversion) to maintain the documentation. Or at least the most > important or entry points of the documentation which will still stay on our > wiki (ie Confluence) > > I think that by creating MarkDown files (or other types but we already > started with README.ME for Gradle) and implementing > https://issues.apache.org/jira/browse/OFBIZ-7723 "Use Pandoc to integrate > our README.MD from repo to Confluence" we could not only easily share the > burden of maintaining documentation but also have an easier and more > reliable way for it (believe me Confluence has still its quirks when > updating big pages) > > So we would create .MD files and locally relies to transform them in .HTML > files still in the svn repo, and then they should be automatically > integrated and updated in Confluence by its HTML connector plugin > > These files would be in the trunk branch or the website one. > > Opinions? >
