Thanks Jason Much appreciated, clap clap!(or to use dev-lingua, mch a9d; -clp clp) As soon as I get some time, I can try it out. If I manage, then it's both fool proof and africa proof (in sierra leone)
Johan > Hi Jens and others, > I have added a bit more detail to the document about how to create > documentation. I am attaching a PDF file along with this email. As you > can see, we still need to do a bit of work on rendering the PDF > doucment properly (URLs are not rendered as they should be) but > otherwise, I think the document should be readable, and hopefully > enough to get started. I am just in the process of commiting the > changes to the documentation branch. > > I would be happy to help you get started, as I would really like to > see this part of DHIS take off a bit. High quality documentation is > sorely needed. The transition to docbook as a primary source of > documentation should not hinder this process, but if too many people > find it too difficult to use "bzr" and edit XML documents (even with > nice editors) then we really need to re-evaluate whether it is > feasible or not. > > Hope the doucment helps. Let me know if you need further guidance. > > Best regards, > Jason > > > On Thu, Sep 24, 2009 at 9:54 PM, Jens Kaasbøll <[email protected]> wrote: >> Jason and others, >> Thanks for this initiative. A structured approach to documentation will >> be >> the right, professional way. >> >> However, in the area of user documentation and tutorials, there will be >> people like me, who are not software developers, and who do not >> understand >> what we should do with the code >> bzr pull lp:~dhis2-documenters/dhis2/dhis2-docbook-docs >> >> There are also people who could contribute, who come from the health >> background without being computer scientists, and who would also feel >> alienated by the ideas of XML, structured documents, etc. I could take >> on >> the challenge of trying to accommodate these, but then I would need >> - to be included in the documentation group >> - to get a crash course on bzrs and other TLAs. >> >> Best regards, >> Jens Kaasbøll >> Univ Oslo >> >> >> On 17.09.2009 22:59, Jason Pickering wrote: >>> >>> OK, i think i solved that problem as well. I created a new team >>> (dhis2-documenters). The new branch is available here. >>> >>> bzr pull lp:~dhis2-documenters/dhis2/dhis2-docbook-docs >>> >>> Let me know if you want to be added to this team. I think I have done >>> everything correctly, but not sure. >>> >>> Best regards, >>> Jason >>> >>> >>> >>> 2009/9/17 Jason Pickering <[email protected]>: >>>> >>>> I went ahead and created a separate branch for the docbook >>>> documentation effort and it can be found here. >>>> >>>> bzr branch lp:~dhis2-devs/dhis2/dhis2-docbook-docs >>>> >>>> I am not that familiar with Launchpad, but it would seem that perhaps >>>> a separate group/team should be added as the owner should be added >>>> instead of the DHIS2 devs so that access could be controlled? >>>> >>>> Regards, >>>> Jason >>>> >>>> >>>> 2009/9/17 Jason Pickering <[email protected]> >>>>> >>>>> Hi Lars, >>>>> >>>>> Glad to see you had a chance to review it. I hope it will catch on. I >>>>> know it is a bit more effort, but with all those semi-WYSIWYG editors >>>>> out >>>>> there, it is not much more difficult that creating a Word document. >>>>> There >>>>> are going to be some compromises of course in terms of layout >>>>> initially. The >>>>> HTML is rendered a bit better now with the addition of a style sheet, >>>>> but it >>>>> will probably take a lot more tweaking. However, the important thing >>>>> to >>>>> remember is that any documentation, even if it is a bit ugly, is >>>>> better than >>>>> none at all! We still need to figure out what to do with the DokuWiki >>>>> and >>>>> other pockets of documentation out there. >>>>> >>>>> I think that creation of a separated branch would be the way to go in >>>>> the long run. Most people that want to contribute to documentation do >>>>> not >>>>> generally need all of the source code as well, and if the devs want >>>>> to >>>>> contribute to the documentation, well, it is simple enough to do >>>>> this. >>>>> Before we do this however, I think we should somehow formally endorse >>>>> that >>>>> DocBook (or similar presentation neutral XML documents) is the way we >>>>> want >>>>> to go. >>>>> >>>>> I am still willing to coordinate the effort for the time being. This >>>>> may >>>>> be a better short-term solution, so that we can continue to guage >>>>> what the >>>>> interest is in heading this direction with the documentation. >>>>> Thinking >>>>> long-term, I suppose it is no problem that the documentation is in a >>>>> separated branch? Ideally, with some sort of integrated help system >>>>> that is >>>>> able to access the documentation directly, we would need to include >>>>> the >>>>> documentation build as part of the entire DHIS2 build process. I >>>>> guess this >>>>> is not an issue, but as I have said previously, maven is just juju >>>>> for me. >>>>> But thank goodness, we have Lars. :) >>>>> >>>>> >>>>> >>>>> Best regards, >>>>> jason >>>>> >>>>> >>>>> >>>>> >>>>> 2009/9/17 Lars Helge Øverland <[email protected]> >>>>>> >>>>>> On Tue, Sep 15, 2009 at 10:44 PM, Jason Pickering >>>>>> <[email protected]> wrote: >>>>>>> >>>>>>> I have just committed in 731 some changes to the documentation >>>>>>> system. >>>>>>> After a bit of experimentation, it would seem that at least for >>>>>>> now, the >>>>>>> maven plugin docbkx is a better choice than the previous >>>>>>> dependency. I was >>>>>>> having issues with the other dependency, so thought I would try >>>>>>> some others. >>>>>>> Anyway.. >>>>>>> >>>>>>> Just execute.. >>>>>>> >>>>>>> mvn docbkx:generate-html to generate HTML >>>>>>> or >>>>>>> mvn docbkx:generate-pdf to generate PDF files for the documents >>>>>>> that >>>>>>> are present. >>>>>>> >>>>>>> There seem to be a lot more possibilities with this dependency, but >>>>>>> it >>>>>>> is a rather heavy download the first time you try and compile the >>>>>>> documentation (at least in Zambia). >>>>>>> >>>>>>> You can read about it here. >>>>>>> >>>>>>> http://docbkx-tools.sourceforge.net/ >>>>>>> >>>>>>> One of the reasons that I decided to move to this for now was that >>>>>>> it >>>>>>> seems to be under active development, actually has a mailing list, >>>>>>> and good >>>>>>> enough documentation for me to understand, (which must mean it is >>>>>>> pretty >>>>>>> good. Maven is still pure magic for me.) >>>>>>> >>>>>>> I have not added a CSS yet for the HTML files, so they still look >>>>>>> crappy, but I guess we could make one similar to the DHIS CSS in >>>>>>> order to >>>>>>> standardize the look and feel. >>>>>>> >>>>>>> Let me know what your mileage is. >>>>>>> >>>>>>> Best regards, >>>>>>> Jason >>>>>> >>>>>> Hi, >>>>>> >>>>>> I have just had a look at this, a few comments: >>>>>> >>>>>> I have reorganized the directory structure a little. I put the maven >>>>>> project in a separate directory called "dhis-documentation-docbook" >>>>>> and used >>>>>> the same name for the project's artifact id. Also removed the >>>>>> packaging: pom >>>>>> element, which now makes it possible to execute "mvn >>>>>> eclipse:eclipse" and >>>>>> then import the project directly into eclipse. All this to make it >>>>>> conform >>>>>> to the maven projects in the system. >>>>>> >>>>>> I have tried out a few docbook-capable xml editors. My favourite was >>>>>> Serna Free 4.2, which formats the xml nicely and makes it easy to >>>>>> insert/modify elements in the document. It is free and under active >>>>>> development. Vex worked reasonably well, but is not so easy-to-use >>>>>> as Serna. >>>>>> Also the Eclipse plugin version did not work in my Eclipse >>>>>> installation >>>>>> (Galileo 3.5) and I had to download the stand-alone version (my >>>>>> guess is >>>>>> that this happens because it is no longer under active development.) >>>>>> >>>>>> http://www.syntext.com/products/serna-free/ >>>>>> >>>>>> One question is how to provide access to documentation writers. By >>>>>> giving people write access to the documentation we also give them >>>>>> write >>>>>> access to the whole branch, including the source code, which is >>>>>> something we >>>>>> don't want to do. A weakness with Launchpad is that we cannot give >>>>>> people >>>>>> access to only parts of a branch. My suggestion is to create a new, >>>>>> dedicated branch for the documentation. >>>>>> >>>>>> Finally I want to thank Jason for taking the lead on this important >>>>>> work... I hope other people using the system will follow his example >>>>>> and >>>>>> contribute to this process. >>>>>> >>>>>> >>>>>> cheers >>>>>> >>>>>> Lars >>>>>> >>>>>> >>>>>> >>> >>> _______________________________________________ >>> Mailing list: https://launchpad.net/~dhis2-devs >>> Post to : [email protected] >>> Unsubscribe : https://launchpad.net/~dhis2-devs >>> More help : https://help.launchpad.net/ListHelp >> >> > _______________________________________________ > Mailing list: https://launchpad.net/~dhis2-devs > Post to : [email protected] > Unsubscribe : https://launchpad.net/~dhis2-devs > More help : https://help.launchpad.net/ListHelp > _______________________________________________ Mailing list: https://launchpad.net/~dhis2-devs Post to : [email protected] Unsubscribe : https://launchpad.net/~dhis2-devs More help : https://help.launchpad.net/ListHelp
