On first reading, I had understood Frédéric Demains' comment quoted below without appreciating its potential effect. In case others may have passed over the comment with a similar mistaken appreciation, I will clarify Frédéric's comment now that I have understood properly. [First a simple statement clarifying my own previously given comments in which it should still be remembered that the documentation format should be a choice of those doing the most work on the documentation. AsciiDoc is merely a simple format for editing documentation for use in DocBook on export. AsciiDoc is not an alternative to DocBook as such. AsciiDoc is expressly designed to provide DocBook formatting, widely considered the preferred base format for free software documentation.] What Frédéric explained below gives an additional perspective on the ease of use encourages more contributions advantage which I had given as the first advantage for AsciiDoc in the list I had prepared of advantages and disadvantages, http://lists.katipo.co.nz/public/koha/2009-October/020807.html . . As a direct consequence of AsciiDoc using a plain text format, programmers may be inclined to use AsciiDoc to document their work as part of the programming process, perhaps even in the same patch. Otherwise, contributing to documentation is a separate process which programmers avoid completely. Any prospect of having the manual updated by those writing the programming code as their patches are applied to the code in one step is very significant advantage. Programmer changes to the manual as might be needed parallel to a code change would apply to the version of the manual corresponding to the version of the software in which the code change would be introduced. If even one programmer could be encouraged to document his work just a little as he coded it, there would be much less time spent identifying how things work in the first place for the manual. Less time of the documentation manager and others would be needed identifying what needs to be described in the manual. More time could be available for ensuring that the description is clear for all users and other good purposes. Using the DocBook format directly should not stop programmers from updating the manual, although, it might preclude updates to the manual in the same patch and would require a greater effort. In reality, any documentation editing format which requires much expenditure of time on the part of programmers would only increase the prevalent tendency of programmers not to document their own work. Programmers need any encouragement which may be obtained to better appreciate the importance of including comments in the code which they write, especially for the benefit other programmers. They also need any possible encouragement to document their own work for everyone. Thomas Dukleth Agogme 109 E 9th Street, 3D New York, NY 10003 USA http://www.agogme.com +1 212-674-3783 On Tue, October 20, 2009 20:32, Frederic Demians wrote:
Thomas, you can add that asciidoc operates very well with developers workflow. It means it can be directly integrated in Koha git main repository (or as submodule), and then, when a developer add a new functionally or modify an existing one he can document it immediately, being not intimated by DocBook schema and editing process. It works this way in git project itself where there is no wall between developers and technical redactors.
To get the picture, take a look at a patch like this one on git main repo:
-- Frédéric