Inline...
Le 18/01/2018 à 13:54, Sharan Foga a écrit :
Hi Taher
I've included some comments inline.
On 2018-01-17 16:54, Taher Alkhateeb <slidingfilame...@gmail.com> wrote:
So I have thought of a few ways to implement our documentation
structure and I would like to share my ideas with everyone to see what
you prefer to go with. Here goes:
- First, let's categorize documentation as:
- component-specific
- general documentation
I like this as it is a simple and easy way for us to do our first split. In the
past we have tried to put everything together in a way that doesn't really fit,
so doing an initial is it this or that, makes it a lot easier.
+1
- component specific documentation lives inside the component in
"/src/docs/asciidoc". It is a self contained piece of documentation.
- Every component has only _one_ publishable document. There is a
methodology in asciidoctor to denote public and private documents.
private documents will not be published but only included in other
documents. This way we can make a modular documentation for each
component while publishing only one output.
I like the idea of only one publishable document per component. That means that
we have a fixed scope for what the documentation needs to cover (so no
documentation creep). I'm sure we will get interlinking between components so
can plan for it and link when ready.
+1 and +1 for inter-links idea
- general documentation (i'm still scratching my head over this one)
could be placed maybe in framework/base. What it does is explain high
level information about the framework and explain general conceptual
principles of how things work.
I'm not sure this can be called general documentation. I was thinking at another place initially, one place where people should look intuitively, like
a documentation sub-dir of root. But we need to define what we call general documentation.
- We can combine the entire documentation of everything (framework +
applications) in a single document that references all the other
documents and maybe we can place it at the top-level directory and
call it something like ofbiz-documentation.adoc
As long as people can easily navigate it and find what they want quickly then
one document could be the solution. At least we can start with that and if does
start to become too heavy then look at re-arranging it or splitting it up.
That sounds like a good idea, finding an ofbiz-documentation.adoc file is as easy as finding a documentation sub-dir of root. But then we need to
remember that it's not often the content that confuse people but how to access it. So we need to think about the structure of this document (like
separating end users and technical doc at the 1st level. Maybe we can think about having end users and technical doc separated in component?
In the past I think all the details from the online help were published as a
consolidated html file via the OFBiz cms. I think it was too linked to the
individual screens so as standalone document without the screens, it wasn't as
useful as it could be.
I think people were also not much aware of this document, so it got not much
critics and was not improved
- Plugins are not included in the full documentation, they are self
contained and are not part of the _big_ published manual. instead each
plugin has its own mini manual.
+1 on this. We will have to maintain the official plugin documentation, and I
would see that people writing their own plugins can use this same mechanism to
include their specific documentation.
Sure +1!
- We declare three gradle tasks similar to the below:
- "./gradlew publishComponentDocs": publish documentation for a
specific component / plugin which requires a componentName flag.
- "./gradlew publishAllComponentsDocs": publish documentation for
all components / plugins
- "./gradlew publishOfbizDocs": publish the master documentation
manual that combines everything.
As per your later response, I think we could reduce the gradle tasks to one for
the framework+core application docs and one for the plugins.
Thanks for sharing - you have some good ideas here. Let's keep the discussion
going :-) so anyone with other ideas, comments and feedback, please feel free
to join the conversation.
I agree, let's continue to share :)
Jacques
Thanks
Sharan
This is a brain dump so I leave it to you fine folks to refine the
ideas and decide where we should go.
Cheers,
Taher Alkhateeb
On Wed, Jan 17, 2018 at 6:08 PM, Craig Parker <cr...@fossfolks.com> 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"<sha...@apache.org> 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 <slidingfilame...@gmail.com> 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
<slidingfilame...@gmail.com> 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
