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?
