Hi Sharan, Craig,
We already have a document that consolidates many smaller documents into itself, but as said Sharan in another reply it got not much attention because
it was maybe not statisfying (though had interesting info)
https://demo-trunk.ofbiz.apache.org/cmssite/cms/APACHE_OFBIZ_HTML
My 2cts
Jacques
Le 18/01/2018 à 13:31, Sharan Foga a écrit :
Hi Craig
Generally I was thinking about how it was going to be laid out. So if you think
about one big consolidated OFBiz Guide that contains both technical and user
guide info, then what would that look like? How would you structure the one
consolidated output?
I don't think that it would necessarily need to mirror the exact structure of
the menus - it just depends on how it's linked to the overall process (if you
are thinking user docs). Also some of the things we need to write about won't
appear anywhere in the menus - so we'll need a general place for that.
My comment was also about the format of each of the source documents to ensure
consistency. Since we are going to be consolidating many smaller documents into
one big one, so it needs to look like they belong together.
Hope that makes it clearer.
Thanks
Sharan
On 2018-01-17 16:08, Craig Parker <[email protected]> wrote:
I think the doc structure ought to mirror the menu in the software, or
are you talking about how a doc itself is laid out?
On 01/17/2018 09:25 AM, Sharan Foga wrote:
Hi Taher
Great work! I tried it out and found it simple and easy to use (and write!).
When can we start writing ? :-)
I was thinking to start with basic descriptions of each of the applications,
then see how it evolves from there. We can maybe recover some documentation
content from various sources including our existing online help system and the
wiki.
The documentation structure will maybe need some thought, and we may need to
sort out some common template or guidelines around it.
Thanks
Sharan
On 2018-01-14 12:33, "Sharan Foga"<[email protected]> wrote:
Excellent news Taher!
Thanks very much for your effort on this. I'll aim to try it out this week and
come back with any feedback.
Thanks
Sharan
On 2018-01-12 17:36, Taher Alkhateeb <[email protected]> wrote:
Hello everyone,
Sorry for the delay on my part, I got a little preoccupied. Anyway, I
have a small patch in [1] that provides the PoC for integrating
asciidoctor with OFBiz. I also provided in the the JIRA [1]
instructions on how to run it. Essentially, this allows you to create
documentation for any component by simply creating a src/docs/asciidoc
directory and putting files inside.
This solution is flexible and allows us to build bigger designs on top
of it. Please review it and tell me if you like the general design.
[1] https://issues.apache.org/jira/browse/OFBIZ-9873
On Tue, Oct 17, 2017 at 11:01 AM, Taher Alkhateeb
<[email protected]> 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
