[Koha] Koha Manual in Git

[Thomas Dukleth]

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:
>
> http://tinyurl.com/yftmt2m
>
> --
> Frédéric
>
>