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 TaherIt'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
smime.p7s
Description: S/MIME Cryptographic Signature
