You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@ofbiz.apache.org by "jleroux@apache.org" <jl...@apache.org> on 2016/08/20 05:29:33 UTC
Sharing the burden of maintaining documentation
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?
Re: Sharing the burden of maintaining documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
So a specific documentation branch?
Jacques
Le 20/08/2016 � 17:32, Pierre Smits a �crit :
> Jacques,
>
> It seems to me that documentation is another work by the project (the other
> 3 being: the code base, the demo site and the website).
> So a repo outside of the control of the project (or even the ASF) is out of
> the question.
>
>
> Best regards,
>
> Pierre Smits
>
> ORRTIZ.COM <http://www.orrtiz.com>
> OFBiz based solutions & services
>
> OFBiz Extensions Marketplace
> http://oem.ofbizci.net/oci-2/
>
> On Sat, Aug 20, 2016 at 5:06 PM, Jacques Le Roux <
> jacques.le.roux@les7arts.com> wrote:
>
>> Thanks Pierre,
>>
>> This is an idea to discuss indeed. You mean a repo outside of the ASF repo
>> or a different branch than trunk or website?
>>
>> Jacques
>>
>>
>> Le 20/08/2016 � 08:27, Pierre Smits a �crit :
>>
>>> IMO, we should not have this kind of documentation in the standard
>>> repository, as it creates bloatware in the application. Better would be to
>>> have it it in seperate repository.
>>>
>>> Best regards
>>>
>>> Pierre Smits
>>>
>>> ORRTIZ.COM <http://www.orrtiz.com>
>>> OFBiz based solutions & services
>>>
>>> OFBiz Extensions Marketplace
>>> http://oem.ofbizci.net/oci-2/
>>>
>>> On Sat, Aug 20, 2016 at 7:29 AM, jleroux@apache.org <jl...@apache.org>
>>> 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?
>>>>
>>>>
Re: Sharing the burden of maintaining documentation
Posted by Pierre Smits <pi...@gmail.com>.
Jacques,
It seems to me that documentation is another work by the project (the other
3 being: the code base, the demo site and the website).
So a repo outside of the control of the project (or even the ASF) is out of
the question.
Best regards,
Pierre Smits
ORRTIZ.COM <http://www.orrtiz.com>
OFBiz based solutions & services
OFBiz Extensions Marketplace
http://oem.ofbizci.net/oci-2/
On Sat, Aug 20, 2016 at 5:06 PM, Jacques Le Roux <
jacques.le.roux@les7arts.com> wrote:
> Thanks Pierre,
>
> This is an idea to discuss indeed. You mean a repo outside of the ASF repo
> or a different branch than trunk or website?
>
> Jacques
>
>
> Le 20/08/2016 à 08:27, Pierre Smits a écrit :
>
>> IMO, we should not have this kind of documentation in the standard
>> repository, as it creates bloatware in the application. Better would be to
>> have it it in seperate repository.
>>
>> Best regards
>>
>> Pierre Smits
>>
>> ORRTIZ.COM <http://www.orrtiz.com>
>> OFBiz based solutions & services
>>
>> OFBiz Extensions Marketplace
>> http://oem.ofbizci.net/oci-2/
>>
>> On Sat, Aug 20, 2016 at 7:29 AM, jleroux@apache.org <jl...@apache.org>
>> 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?
>>>
>>>
>
Re: Sharing the burden of maintaining documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
Thanks Pierre,
This is an idea to discuss indeed. You mean a repo outside of the ASF repo or a different branch than trunk or website?
Jacques
Le 20/08/2016 � 08:27, Pierre Smits a �crit :
> IMO, we should not have this kind of documentation in the standard
> repository, as it creates bloatware in the application. Better would be to
> have it it in seperate repository.
>
> Best regards
>
> Pierre Smits
>
> ORRTIZ.COM <http://www.orrtiz.com>
> OFBiz based solutions & services
>
> OFBiz Extensions Marketplace
> http://oem.ofbizci.net/oci-2/
>
> On Sat, Aug 20, 2016 at 7:29 AM, jleroux@apache.org <jl...@apache.org>
> 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?
>>
Re: Sharing the burden of maintaining documentation
Posted by Pierre Smits <pi...@gmail.com>.
IMO, we should not have this kind of documentation in the standard
repository, as it creates bloatware in the application. Better would be to
have it it in seperate repository.
Best regards
Pierre Smits
ORRTIZ.COM <http://www.orrtiz.com>
OFBiz based solutions & services
OFBiz Extensions Marketplace
http://oem.ofbizci.net/oci-2/
On Sat, Aug 20, 2016 at 7:29 AM, jleroux@apache.org <jl...@apache.org>
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?
>
Re: Sharing the burden of maintaining documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
Mmm, I missed so say something about what leads me to write this email, let me explain.
Sharan shared this tweet https://twitter.com/opensourceway/status/766000900582158336
I then looked into the article and finally landed there https://github.com/nayafia/contributing-template/blob/master/CONTRIBUTING-template.md
I thought it could be a good idea to have this adapted in our trunk root folder
I remember Sharan also shared a tweet where it was more question of roadmap. I can't find it back, but that was also one of the reasons I revivified
https://cwiki.apache.org/confluence/display/OFBADMIN/New+Features+Roadmap+-+Living+Document
Jacques
Le 20/08/2016 � 07:29, jleroux@apache.org a �crit :
> 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?
>
Re: Sharing the burden of maintaining documentation
Posted by Sharan Foga <sh...@gmail.com>.
Hi All
The documentation discussion has come up a few times and I think the last time we talked about some of the topics that are coming up again here.
I agree that some form of version control will help us and means that it can be linked to a release.
On the choice of tool, thanks Taher for the brief pros and cons summary of options.
Docbook \u2013 this has been available in OFBiz for a while, but the implementation we have of it, is not a complete one (i.e. only limited tags work) which means there was something not quite right with the way that we want to use it. I seem to remember it was related to speed of the way things are rendered using it. (Also to be able to use the Webhelp we would have to convert the documents to HTML to display it.)
AsciiDoc \u2013 I had a brief go with this too and did find it a lot easier to use but a little basic.
Dita \u2013 Looking at what we want the documentation to achieve, (structured multiple formats, re-use, etc) I think Dita could be a good option that could provide a lot of flexibility and adapt to the project needs. Ron and I had a brief go at setting up a DITA proof of concept. I didn't get very far mainly because of I didnt have any full examples of the documentation I wanted to produce. (Think of it of like having a blank page and someone saying produce the best documentation ever! Where do you start?)
BTW - I'm doing some work offline with Craig Parker (some of you might have remembered that he posted a thread a while ago about getting a basic user guide setup). I think if we can at least pull together an example guide and the information that needs to be in it, then it will be easier to analyse and transform that information in a range of documentation settings where it can be re-used (and that strongly ties in with the Dita model.)
Thanks
Sharan
On 2016-08-21 09:40 (+0200), Taher Alkhateeb <sl...@gmail.com> wrote:
> Yeah I really like asciidoc too. I'm making a comparison below specific to
> our community for making a choice. Please feel free to correct it or
> complete it, it's just a quick idea dump.
>
> DocBook pros:
> - Mature, many books available to read
> - Excellent documentation
> - Already exists in OFBiz
> - Tools and utilities are numerous
>
> DocBook cons:
> - Not modular, more suited for books and articles
> - Verbose XML
> - Very complex vocabulary with hundreds of tags and countless combinations
>
> AsciiDoc pros:
> - Human friendly
> - Minimal learning curve for new users
> - Despite simple syntax it has powerful publishing capabilities
> - Good documentation
>
> AsciiDoc cons:
> - No books (AFAIK) and online troubleshooting is minimal
> - Not modular similar to DocBook
> - Tooling support is lacking and few editors support it like vim, emacs,
> gedit.
>
> Dita pros:
> - Mature and many books available to read
> - Most utilized standard for content authoring and deployed in many large
> contexts
> - Good documentation (I think DocBook is much better though)
> - Modular: this is the single most powerful feature. It allows reusing
> content and even parameterized content. The same piece of content could be
> used in a tutorial, online help and reference documentation for example.
> - Good tooling support (dita-ot) but again nothing beats DocBook in that
> area.
>
> Dita cons
> - Verbose XML syntax
> - Steeper learning curve due to vocabulary (but nothing compared to DocBook)
> - Not very well suited for long documentation (not sure if we have it /
> need it)
>
> I hope I got things right. I think all solutions above are good and I lean
> slightly towards dita because of the modularity aspect.
>
> Taher Alkhateeb
>
> On Aug 21, 2016 9:03 AM, "Jacques Le Roux" <ja...@les7arts.com>
> wrote:
>
> > Le 20/08/2016 à 21:15, Jacques Le Roux a écrit :
> >
> >> - 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
> >>
> > Err, forgot "AsciiDoc" in this sentence :/
> > Note: there are AsciiDoc plugins for Eclipse and IntelliJ. With Pandoc you
> > can transform almost all formats to another
> >
> > Interesting contradictory PoV on DITA http://idratherbewriting.com/2
> > 015/01/28/10-reasons-for-moving-away-from-dita/
> >
> > Jacques
> >
> >
>
Re: Sharing the burden of maintaining documentation
Posted by Taher Alkhateeb <sl...@gmail.com>.
Yeah I really like asciidoc too. I'm making a comparison below specific to
our community for making a choice. Please feel free to correct it or
complete it, it's just a quick idea dump.
DocBook pros:
- Mature, many books available to read
- Excellent documentation
- Already exists in OFBiz
- Tools and utilities are numerous
DocBook cons:
- Not modular, more suited for books and articles
- Verbose XML
- Very complex vocabulary with hundreds of tags and countless combinations
AsciiDoc pros:
- Human friendly
- Minimal learning curve for new users
- Despite simple syntax it has powerful publishing capabilities
- Good documentation
AsciiDoc cons:
- No books (AFAIK) and online troubleshooting is minimal
- Not modular similar to DocBook
- Tooling support is lacking and few editors support it like vim, emacs,
gedit.
Dita pros:
- Mature and many books available to read
- Most utilized standard for content authoring and deployed in many large
contexts
- Good documentation (I think DocBook is much better though)
- Modular: this is the single most powerful feature. It allows reusing
content and even parameterized content. The same piece of content could be
used in a tutorial, online help and reference documentation for example.
- Good tooling support (dita-ot) but again nothing beats DocBook in that
area.
Dita cons
- Verbose XML syntax
- Steeper learning curve due to vocabulary (but nothing compared to DocBook)
- Not very well suited for long documentation (not sure if we have it /
need it)
I hope I got things right. I think all solutions above are good and I lean
slightly towards dita because of the modularity aspect.
Taher Alkhateeb
On Aug 21, 2016 9:03 AM, "Jacques Le Roux" <ja...@les7arts.com>
wrote:
> Le 20/08/2016 à 21:15, Jacques Le Roux a écrit :
>
>> - 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
>>
> Err, forgot "AsciiDoc" in this sentence :/
> Note: there are AsciiDoc plugins for Eclipse and IntelliJ. With Pandoc you
> can transform almost all formats to another
>
> Interesting contradictory PoV on DITA http://idratherbewriting.com/2
> 015/01/28/10-reasons-for-moving-away-from-dita/
>
> Jacques
>
>
Re: Sharing the burden of maintaining documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
Le 20/08/2016 � 21:15, Jacques Le Roux a �crit :
>> - 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
Err, forgot "AsciiDoc" in this sentence :/
Note: there are AsciiDoc plugins for Eclipse and IntelliJ. With Pandoc you can transform almost all formats to another
Interesting contradictory PoV on DITA http://idratherbewriting.com/2015/01/28/10-reasons-for-moving-away-from-dita/
Jacques
Re: Sharing the burden of maintaining documentation
Posted by Taher Alkhateeb <sl...@gmail.com>.
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 <
jacques.le.roux@les7arts.com> 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" <ja...@les7arts.com>
>> 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, "jleroux@apache.org" <jl...@apache.org>
>>>> 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?
>>>>>
>>>>>
>>>>>
>
Re: Sharing the burden of maintaining documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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" <ja...@les7arts.com>
> 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, "jleroux@apache.org" <jl...@apache.org> 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?
>>>>
>>>>
Re: Sharing the burden of maintaining documentation
Posted by Taher Alkhateeb <sl...@gmail.com>.
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" <ja...@les7arts.com>
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, "jleroux@apache.org" <jl...@apache.org> 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?
>>>
>>>
>
Re: Sharing the burden of maintaining documentation
Posted by Jacques Le Roux <ja...@les7arts.com>.
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, "jleroux@apache.org" <jl...@apache.org> 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?
>>
Re: Sharing the burden of maintaining documentation
Posted by Taher Alkhateeb <sl...@gmail.com>.
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, "jleroux@apache.org" <jl...@apache.org> 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?
>