I'm not sure, but I think we should document "everything" like user, developer, etc. It's up to all of us to decide and I have no strong opinion on this.
On Wed, Jan 17, 2018 at 6:56 PM, Craig Parker <cr...@fossfolks.com> wrote: > And I'm just realizing... You're not talking end user docs are you? > > > > On 01/17/2018 10:54 AM, Taher Alkhateeb 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 >> - 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 >>> >>> >
