Hi Sharan,
Yes I'm pretty sure we will still need the wiki. For technical points which don't specially fit in source and also some kind of user documentation,
but the less the better.
Jacques
Le 18/10/2017 à 10:28, Sharan Foga a écrit :
Hi
I would say the first and easier focus is to complete the online help. Telling
people how to use the screens and applications is a basic requirement that we
haven't fulfilled for OFBiz yet. Once we have that then we can see how it can
be expanded to incorporate more general details. I think the issue we have had
over the years is that OFBiz is so big that it's difficult to know where to
start.
At least if we can give people information about the application they are
using, and how to use the screens, then that will give them enough to get
going. For content we could review the existing help that we have and update it
into a standard format or template so that it is consistent.
We may also find that we still need the wiki for something so let's see what
happens
Thanks
Sharan
On 2017-10-17 13:21, Jacques Le Roux <jacques.le.r...@les7arts.com> wrote:
Yes thanks Taher to have picked this again,
I agree with all what have been said so far.
You know my preference for asscidoc and asciidoctor. Using the asciidoctor
Gradle plugin seems logical to me.
I'm all for having all the documentation inside the source. I had even created
a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423
Questions:
1. Should we continue to provide an online help? Would we reuse/upgrade the
current one?
2. Where to put the common documentation? In common or commonext component or
in a new documentation folder? Later seems easier for newbies, name
says all.
3. I use pandoc to create (from some .md files) md.html files in
tools\wiki-files imported in wiki pages. I regularly use a .bat for that. Would
we
replace also our current .md files?
Jacques
Le 17/10/2017 à 11:25, Michael Brohl a écrit :
Big +1 for this initiative!
I have not much to add to Taher's proposal and Sharan's viewpoint.
I assume that we can use any Asciidoc editor and need not to use Asciidoctor?
I think we have to decide what we will do with our Wiki based documentation
then. If we have up-to-date documentation in the components and can
generate up-to-date documentation every night, pretty much of the Wiki
documentation would be obsolete. A simple link to the generated documentation
would be enough, right?
For new code in framework and plugins, I would strongly recommend to have
mandatory documentation as part of the first commit to the codebase to
assure a good initial start.
I think we should just start with a proof-of-concept by moving some small part
of the documentation to Asciidoc and into the codebase.
Would be a great starting point for new contributors also.
Best regards,
Michael
Am 17.10.17 um 10:30 schrieb Sharan Foga:
Hi Taher
It's great that this conversation has started again. It would be great to
actually start to do something about the integrated help system within
OFBiz itself. We have found limitations with the docbook implementation we
have, so now have a better idea of what we want to achieve.
In the past we've talked a lot about DITA but to me it seemed a lot more
complex to understand, structure and generally get started. I've briefly
played about with Ascidoc and it seems pretty simple enough to get the hang of
and that to me is an important thing. I also like the idea of being
able to render multiple formats (and it would be good to make them look nicer
and easier to read).
Getting a good and functioning help framework into our codebase is long overdue
and I'm sure will add some great benefits and also encourage
documentation contributions from our community.
Big +1 from me!
Thanks
Sharan
On 17/10/17 10:01, Taher Alkhateeb wrote:
Hello Folks,
We've had this discussion multiple times in the past, but I think I
have a more concrete idea this time for solving this problem. In the
past few weeks we've been working internally in Pythys to figure out
the best way to write and distribute documentation, and I think most
of that is applicable to OFBiz.
In a nutshell, here is the idea (practically) for how to proceed:
- The documentation language to use is Asciidoc
- The documentation tool is Asciidoctor
- Publishing happens through Gradle using the asciidoctor gradle
plugin (not the OFBiz framework or anything else).
- The only place where we write documentation is inside the code base
- Every component contains its own documentation
- General documentation goes to either a standalone directory or a
generic component like common or base
- As much as possible, documentation files are small and focused on
one topic. And then other longer documents are constructed from these
snippets of documentation.
- We publish to all formats including PDF for users, or HTML for
embedded help and wiki pages. So OFBiz does not parse docbook for its
help system, instead it just renders generated HTML.
As I've worked extensively with Asciidoc I find it easy to pickup
(like markdown) but also modular (like docbook and dita). It's also
neat that you can sprinkle variables all around in your document so
that update is no longer a painful grepping process.
Would love to hear your thoughts on this.
Cheers,
Taher Alkhateeb
