I agree, actually as experience learned us, to create a good documentation is more a question of structuring the documentation to avoid what we have now in Confluence: a mess with a lot of obsolete (or hard to tell) pages :D

By using asciidoc, a version control tools to have the documentation as OFBiz 
code it should be easier to avoid that.

I note though that it's all about reviewing, it was already possible in Confluence but it did not work because it was harder to follow, organise and structure.

I think we already agreed about using Confluence as less as possible. Mostly 
for important generic points like Guides, FAQ, Tutos, etc.

In Confluence we can also import data from svn, it's already used for some 
specific stuff like Gradle.

I use https://svn.apache.org/repos/asf/ofbiz/tools/updateWiki.bat for that, not sure it's the best way, but for now it helps. The basic idea is to have a SPOF (ie only one place for the source).

So we could for instance migrate, after cleaning and deleting a lot, the important Confluence content to keep in a main documentation sub-dir (under OFBiz root) under a format or another and render it automatically in HTML format to import into Confluence

I read that some projects use o want to use BuibBot/Jenkins and 
https://jekyllrb.com/ for doing somehow that

Just an idea...

Jacques


Le 08/02/2018 à 14:25, Michael Brohl a écrit :
+++1 for manually reviewing, updating, restructuring and enhancing the 
documentation instead of copy & paste!

We know that the documentation has very different quality, is sometimes 
outdated or too brief etc.

I think it is of more value to take the chance to make the documentation itself better in the course of the migration instead of simply having the old state in a new format.

We should maybe also agree on writing new documentation (or anhancing a good amount of documentation) directly in the new format instead of putting it in confluence 8if applicable)?

Thanks,

Michael


Am 08.02.18 um 11:33 schrieb Taher Alkhateeb:
It is heartwarming to see you fine people signing up. I am thrilled
and looking forward to working with you. And I have to say Sharan
knows how to bring us together, so thank you!

In reference to Olivier's comment regarding using conversion tools, I
would advise to perhaps try to be careful. Our objective is not
necessarily to copy-paste existing documentation, but rather to write
clean, relevant and well thought out documentation. If an old piece of
documentation is good and relevant, we use it, if not, we update it
and clean it, or of it is not useful then we just drop it.

I hope more people feel the urge to sign up. What you folks are going
to achieve is to make OFBiz much more competitive by giving
accessibility to new comers through comprehensive documentation.

On Thu, Feb 8, 2018 at 1:04 PM, Aditya Sharma
<aditya.sha...@hotwaxsystems.com> wrote:
Hi Sharan,

Please count me in.

Thanks and Regards,

*Aditya Sharma* | Enterprise Software Engineer
HotWax Commerce <http://www.hotwax.co/> by HotWax Systems
<http://www.hotwaxsystems.com/>

<https://www.linkedin.com/in/aditya-sharma-78291810a/>

On Thu, Feb 8, 2018 at 2:25 PM, Olivier Heintz <
holivier.li...@ofbizextra.org> wrote:

Hi Sharan,

please add me to the list,

I have start to play with the new tools
I have convert some docbook file to asciidoc with docbookrx tools and make
modification on help data to use the html generated files in the ofbiz
help, it's work's ;-)
If needed, I can convert all docbook files to asccidoc


Regards,



Le 07/02/2018 à 14:32, Sharan Foga a écrit :
Hi Everyone

(Trying again as my first post didn't reach this list)

If you have read the latest project blog post then you will have seen a
section about the discussions that have been happening on our development
list about the new proposed OFBiz documentation framework.
https://s.apache.org/VfxE

It is based on asciidoc and will be able to generate documentation in
various formats. This means that we can start to consolidate our OFBiz
documentation within OFBiz itself and adapt it to any new releases.
Feedback to the proposal have been very positive and once the code is
moved into our current trunk we will need to start some documentation work.
We will be looking for volunteers to become part of a documentation team
that will work on reviewing the documents we already have in the wiki and
other sources, then help to re-structure them to fit into the new
documentation framework model.
Being involved with documentation is a good way to learn OFBiz :-)

So if you are interested in being part of the OFBiz documentation team
then please respond to this message and I will add you to the list.
Thanks
Sharan





--

Jacques Le Roux
400E Chemin de la Mouline
34560 Poussan
04 67 51 19 38
06 11 79 50 28

Reply via email to