Great, it seems we are aiming for similar objectives. Yeah it would be difficult to know where to place "generic" documentation. Perhaps things that are very generic can simply be placed in the base component? I think the choice of the tool would have an influence on where to put things and how to organize them.
On Sat, Aug 20, 2016 at 10:15 PM, Jacques Le Roux < [email protected]> wrote: > Le 20/08/2016 à 20:16, Taher Alkhateeb a écrit : > >> 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. >> > > Yes I agree, due to the level of contributions from contributors in wiki I > think we can use the same process than for code, ie > 1. discuss on dev ML if necessary > 2. patch on Jira > > In summary I suggest the following: >> >> - Minimize the use of short documentation to a few areas where it's useful >> in readme markdown files >> > > +1 > > - Provide full documentation through a powerful publishing solution such as >> DocBook or DITA. >> > > +1, but we need to have a consensus with the tool, Paul and I advocated > for instance > > - 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. >> > > +1, this make sense to me, but I still wonder about the location of very > generic stuff. Why simply not a documentation folder in trunk? > > - Limit the role of the wiki to a few miscellaneous areas or maybe just >> mirroring the reference documentation. >> > > A simple automated mirroring (using Pandoc and HTML import) would be nice > with me > > 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. >> > > Totally agreed, this after a long experience with Confluence. We can even > build graphs from text as Ron proved! I see nothing missing so far... > > > Jacques > > >> 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? >>>>> >>>>> >>>>> >
