Hi Jacques, Thank you for the feedback, based on your input I would summarize as follows:
The problem with confluence and the reason we have a mess in the first place is that it is not under Version Control and it is not part of the code base. It is much easier to update the documentation if it's living side-by-side with your code. Many times for example when I update the build script I just go and fix the readme file immediately in one commit. As for non committers not being able to update I don't think this is a big problem. Yes it might cause a bit of a delay but it goes through the same process as just submitting code. For one thing it is better to have a fresh pair of eyes reviewing before committing if nothing else. So this is why I am recommending a powerful publishing solution, not only for the ability to generate PDF documents but also to interplay with the wiki or any other means of providing documentation to our users. I would like to think of our documentation as being similar to the way we generate javadocs. In summary I suggest the following: - Minimize the use of short documentation to a few areas where it's useful in readme markdown files - Provide full documentation through a powerful publishing solution such as DocBook or DITA. - Have the documentation live inside the code base preferably on the same branch. Why? Because we update code and documentation in the very same commit. - Limit the role of the wiki to a few miscellaneous areas or maybe just mirroring the reference documentation. This in my opinion would be a simpler solution as I find it just so hard to keep the wiki and the code base in sync. Taher Alkhateeb On Aug 20, 2016 8:41 PM, "Jacques Le Roux" <[email protected]> wrote: > Taher, > > Inline > > > Le 20/08/2016 à 08:29, Taher Alkhateeb a écrit : > >> 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. >> > > I agree, we already have such a distinction with several README in > component which leads to pages in wiki (a particular effort from Pierre > Smits) > Those could converted to Markdown and then automatically included using > Pandoc and Confluence HTML import plugin > > >> 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. >> > > For now we have Confluence and a lot of content to maintain or drop there. > > 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? >> > > Yes that would help us to get rid of the mess we have currently in the > wiki. > On the other hand only committers would be able to maintain, when with the > wiki we have, theoretically, also contributors. > By theoretically I mean that I did not see much coming from our > contributors these last times. Maybe they are also impressed by the mess > there. > I believe the best way to make sense of the mess we have in wiki is to > simply organise what is still relevant and drop the rest in archives if it > has some value or in workspaces trash (ie delete) if it has less or no > value. > > We need a consensus... > > Jacques > > >> 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? >>> >>> >
