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 - 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. - 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. - 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 - 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. - 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. 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 > >
