From dev-return-110105-archive-asf-public=cust-asf.ponee.io@ofbiz.apache.org Thu Jan 25 15:00:57 2018 Return-Path: X-Original-To: archive-asf-public@eu.ponee.io Delivered-To: archive-asf-public@eu.ponee.io Received: from cust-asf.ponee.io (cust-asf.ponee.io [163.172.22.183]) by mx-eu-01.ponee.io (Postfix) with ESMTP id 70E95180651 for ; Thu, 25 Jan 2018 15:00:57 +0100 (CET) Received: by cust-asf.ponee.io (Postfix) id 60B6C160C3D; Thu, 25 Jan 2018 14:00:57 +0000 (UTC) Delivered-To: archive-asf-public@cust-asf.ponee.io Received: from mail.apache.org (hermes.apache.org [140.211.11.3]) by cust-asf.ponee.io (Postfix) with SMTP id 78954160C13 for ; Thu, 25 Jan 2018 15:00:56 +0100 (CET) Received: (qmail 1082 invoked by uid 500); 25 Jan 2018 14:00:50 -0000 Mailing-List: contact dev-help@ofbiz.apache.org; run by ezmlm Precedence: bulk List-Help: List-Unsubscribe: List-Post: List-Id: Reply-To: dev@ofbiz.apache.org Delivered-To: mailing list dev@ofbiz.apache.org Received: (qmail 1066 invoked by uid 99); 25 Jan 2018 14:00:50 -0000 Received: from ui-eu-01.ponee.io (HELO localhost) (176.9.59.70) by apache.org (qpsmtpd/0.29) with ESMTP; Thu, 25 Jan 2018 14:00:50 +0000 x-ponymail-agent: PonyMail Composer/0.2 x-ponymail-sender: 31e1cbf2b23a01ea035ee3323fe2ab95950c8284 References: <2d7d170b-e282-ce23-d0fb-f0e7dc1fcd59@les7arts.com> From: Sharan Foga Content-Type: text/plain; charset="iso-8859-1" In-Reply-To: To: Message-ID: X-Mailer: LuaSocket 3.0-rc1 Date: Thu, 25 Jan 2018 14:00:48 -0000 MIME-Version: 1.0 Subject: Re: [Discussion] documentation framework for OFBiz Hi Taher The picture helps :-) I had to do a bit of a double-take but I get it now and a big +1 I like what you are suggesting – very nice. It is not entirely following the menu structure (which is good) instead it is looking at the individual topics. This means that we can make the main document flow a lot easier than simply following what we have in the menus. (e.g We know that you can get to the same place from by different routes on the menus and screens, so focussing on the topic itself will help that.) I think this will give us the flexibility we need. A standard structure helps people know where to put things. Thanks Sharan On 2018/01/25 11:37:02, Taher Alkhateeb wrote: > Hi Everyone, > > So after a little bit of thinking, I came up with an example file > structure for OFBiz documentation which is listed below. The full > OFBiz manual simply points to all the parts in applications, > framework, and themes to complete the documentation. Any ideas or > feedback is welcomed. > > A few points to note: > - Gradle by default ignores any files in the _include sub directory > and so it will only publish the outer document. > - This way, we can publish per component (in isolation) or the whole > documentation by simply publishing the ofbiz-manual.adoc file > - We can further branch out the documentation as needed. > > ofbiz > ├── applications > │ ├── accounting > │ │ └── src > │ │ └── docs > │ │ └── asciidoc > │ │ ├── accounting.adoc > │ │ └── _include > │ │ ├── accounting-intro.adoc > │ │ ├── budgets.adoc > │ │ ├── invoices.adoc > │ │ ├── payments.adoc > │ │ └── understanding-general-ledger.adoc > │ └── humanres > │ └── src > │ └── docs > │ └── asciidoc > │ ├── humanres.adoc > │ └── _include > │ ├── employee-evaluations.adoc > │ ├── human-resources-intro.adoc > │ └── punch-in-punch-out.adoc > ├── framework > │ ├── base > │ │ └── src > │ │ └── docs > │ │ └── asciidoc > │ │ ├── base.adoc > │ │ └── _include > │ │ ├── containers.adoc > │ │ ├── framework-intro.adoc > │ │ └── loading-components.adoc > │ ├── entity > │ │ └── src > │ │ └── docs > │ │ └── asciidoc > │ │ ├── entity.adoc > │ │ └── _include > │ │ ├── entity-conditions-api.adoc > │ │ ├── entity-engine-intro.adoc > │ │ └── mapping-new-database.adoc > │ └── widget > │ └── src > │ └── docs > │ └── asciidoc > │ ├── _include > │ │ ├── form-widgets.adoc > │ │ ├── screen-widgets.adoc > │ │ └── widget-system-intro.adoc > │ └── widget.adoc > ├── ofbiz-manual.adoc > ├── plugins > │ └── example > │ └── src > │ └── docs > │ └── asciidoc > │ ├── example.adoc > │ └── _include > │ ├── example-intro.adoc > │ └── extending-example-widgets.adoc > └── themes > └── common-theme > └── src > └── docs > └── asciidoc > ├── common-theme.adoc > └── _include > ├── ofbiz-themes-intro.adoc > ├── web-assets.adoc > └── why-common-theme.adoc > > On Fri, Jan 19, 2018 at 4:27 PM, Jacques Le Roux > wrote: > > 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 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" 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 > >>>>> 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 > >>>>>> 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 > >>> > >>> > > >