Thank you folks for your feedback. Based on everyone's input, I think perhaps a good way to move forward is by creating a JIRA and making a patch for a PoC.
I think altering the OFBiz help system for now might be a bigger task, so for a start, I think I will write some documentation in multiple places and then let gradle consolidate that into an output manual. Then, based on feedback from you we decide on the next step. So I will proceed with creating a JIRA for an initial PoC. Again, thank you for your thoughts, all constructive and valuable. On Wed, Oct 18, 2017 at 11:47 AM, Jacques Le Roux <[email protected]> wrote: > Hi Sharan, > > Yes I'm pretty sure we will still need the wiki. For technical points which > don't specially fit in source and also some kind of user documentation, but > the less the better. > > Jacques > > > Le 18/10/2017 à 10:28, Sharan Foga a écrit : >> >> Hi >> >> I would say the first and easier focus is to complete the online help. >> Telling people how to use the screens and applications is a basic >> requirement that we haven't fulfilled for OFBiz yet. Once we have that then >> we can see how it can be expanded to incorporate more general details. I >> think the issue we have had over the years is that OFBiz is so big that it's >> difficult to know where to start. >> >> At least if we can give people information about the application they are >> using, and how to use the screens, then that will give them enough to get >> going. For content we could review the existing help that we have and update >> it into a standard format or template so that it is consistent. >> >> We may also find that we still need the wiki for something so let's see >> what happens >> >> Thanks >> Sharan >> >> On 2017-10-17 13:21, Jacques Le Roux <[email protected]> wrote: >>> >>> Yes thanks Taher to have picked this again, >>> >>> I agree with all what have been said so far. >>> >>> You know my preference for asscidoc and asciidoctor. Using the >>> asciidoctor Gradle plugin seems logical to me. >>> >>> I'm all for having all the documentation inside the source. I had even >>> created a Jira for that https://issues.apache.org/jira/browse/OFBIZ-9423 >>> >>> Questions: >>> >>> 1. Should we continue to provide an online help? Would we reuse/upgrade >>> the current one? >>> 2. Where to put the common documentation? In common or commonext >>> component or in a new documentation folder? Later seems easier for newbies, >>> name >>> says all. >>> 3. I use pandoc to create (from some .md files) md.html files in >>> tools\wiki-files imported in wiki pages. I regularly use a .bat for that. >>> Would we >>> replace also our current .md files? >>> >>> Jacques >>> >>> >>> Le 17/10/2017 à 11:25, Michael Brohl a écrit : >>> >>>> Big +1 for this initiative! >>>> >>>> I have not much to add to Taher's proposal and Sharan's viewpoint. >>>> >>>> I assume that we can use any Asciidoc editor and need not to use >>>> Asciidoctor? >>>> >>>> I think we have to decide what we will do with our Wiki based >>>> documentation then. If we have up-to-date documentation in the components >>>> and can >>>> generate up-to-date documentation every night, pretty much of the Wiki >>>> documentation would be obsolete. A simple link to the generated >>>> documentation >>>> would be enough, right? >>>> >>>> For new code in framework and plugins, I would strongly recommend to >>>> have mandatory documentation as part of the first commit to the codebase to >>>> assure a good initial start. >>>> >>>> I think we should just start with a proof-of-concept by moving some >>>> small part of the documentation to Asciidoc and into the codebase. >>>> >>>> Would be a great starting point for new contributors also. >>>> >>>> Best regards, >>>> >>>> Michael >>>> >>>> >>>> Am 17.10.17 um 10:30 schrieb Sharan Foga: >>>>> >>>>> Hi Taher >>>>> >>>>> It's great that this conversation has started again. It would be great >>>>> to actually start to do something about the integrated help system within >>>>> OFBiz itself. We have found limitations with the docbook implementation >>>>> we have, so now have a better idea of what we want to achieve. >>>>> >>>>> In the past we've talked a lot about DITA but to me it seemed a lot >>>>> more complex to understand, structure and generally get started. I've >>>>> briefly >>>>> played about with Ascidoc and it seems pretty simple enough to get the >>>>> hang of and that to me is an important thing. I also like the idea of >>>>> being >>>>> able to render multiple formats (and it would be good to make them look >>>>> nicer and easier to read). >>>>> >>>>> Getting a good and functioning help framework into our codebase is long >>>>> overdue and I'm sure will add some great benefits and also encourage >>>>> documentation contributions from our community. >>>>> >>>>> Big +1 from me! >>>>> >>>>> Thanks >>>>> Sharan >>>>> >>>>> >>>>> On 17/10/17 10:01, 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 >>>>> >>>>> >>>> >>> >
