Hello documentation team and everyone I have created a slightly modified design of the documentation framework with some sample contents in [1]. I highlight the changes below: - Created a new top-level directory called "docs/asciidoc". The reason is so that we have more than one possible manual. - Created "Apache OFBiz User Manual" in docs/asciidoc/user-manual.adoc - Created "Apache OFBiz Developer Manual" in docs/asciidoc/developer-manual.adoc - Created a sample document in the accounting component to show how documents are linked together. - Used a special directive called "leveloffset" in the include directive. This directive shifts the headers of the included document (H2 becomes H3, and so on) so that sub-sections can be published separately. - Created a task called generateOfbizDocumentation to generate the documentation (both PDF and HTML) for framework + core apps - Created a task called generatePluginDocumentation -PpluginId=whatever to generate the documentation for a single plugin.
That's it. It's simple, easy to understand and I think you might like it. Any feedback is welcome, and I'll talk to you soon over Skype. [1] https://issues.apache.org/jira/browse/OFBIZ-9873 On Tue, Jan 30, 2018 at 4:38 PM, Sharan Foga <sha...@apache.org> wrote: > Hi Taher > > I think a documentation team would be a great idea. There are people that > have indicated that they'd like to help out with documentation tasks on the > user list so that is where I'd recruit some people from. As long as people > know what they need to do to create the patches then it will become a funnel > process of getting it committed. > > We need a plan to consolidate the information sitting in the wiki and getting > it put into the documentation framework (and this work will then > significantly clear up the wiki!). > > My availability is pretty bad this week so hope to pick this up again or > start the recruitment campaign next week :-) > > Thanks > Sharan > > On 2018/01/28 10:12:41, Taher Alkhateeb <slidingfilame...@gmail.com> wrote: >> Like Michael I think it is also a minor point. The reason I chose this >> structure is because it is the default one for asciidoctor and is flexible >> for the future, so Paul also makes a good point. Any structure is fine by >> me, the real important work is getting the documentation right which is >> very exciting to me. >> >> I will create a patch soon for a base level structure and publishing >> options for both HTML and PDF. It would be fantastic if we can unify _all_ >> of our documentation here including stuff currently in the wiki. This way >> any changes to code are reflected (probably in the same commit) with the >> relevant documentation. >> >> I think we should start to consider maybe forming a team willing to help. >> This is a big, but extremely important thing to have. If we do this right >> then I think adoption rates would increase and our community would get >> larger. >> >> On Jan 28, 2018 12:19 PM, "Michael Brohl" <michael.br...@ecomify.de> wrote: >> >> Hi Paul, >> >> this is only a minor point for me, it just saves one folder/structure level. >> >> If we want to stay open for other documentation frameworks in the future, >> it might be better to keep the proposed structure. >> >> Best regards, >> >> Michael >> >> >> Am 28.01.18 um 02:54 schrieb Paul Foxworthy: >> >> On 26 January 2018 at 19:53, Michael Brohl <michael.br...@ecomify.de> wrote: >> > >> > >> > with a small modification: I don't think we'll need a two-folder structure >> >> /docs/asciidoc, only /docs should be sufficient, no? >> >> >> >> Hi Michael, >> > >> > We have streamlined the build system in other places by having folders for >> > the source language: groovyScripts, minilang, src/main/java . >> > >> > It means Groovy and other build tools can have default rules for what to do >> > with the contents of a language folder, and allows for the possibility of >> > other languages in future if necessary. >> > >> > The extra layer is only a minor nuisance. I think I'd prefer to keep it. >> > What do you see as the disadvantages? >> > >> > Cheers >> > >> > Paul Foxworthy >> > >> > >>
