[Nut-upsdev] Documentation-related questions

[Eric S. Raymond]

Arnaud Quette <aquette.dev at gmail.com>:
> first, a small sum up of the current status, past work and aims to
> understand the situation:
> - the doc need to be easily maintainable by a non tech guy (though I've
> still not found anybody reliable enough for that),

This is a strong argument in favor of asciidoc for the in-tree
documentation, which is by far the simplest text-formatting markup
I've found yet.  It's a fairly recently-developed technology; I did
not know of it when we last had an in-depth conversation about this.

> - we need to provide at least an html output,

asciidoc does a very good job at this.  For a representative example of 
a document that includes a table, see

http://www.catb.org/~esr/wesnoth/campaign-design-howto.html

Trickier styling is possible with CSS, but IMHO the default asciidoc
styling is just fine, pleasingly light and elegant.

> - many part of the contents of the website and inline doc (ie the docs/
> directory of the source tree) are either redundant or missing on one side or
> the other,
> - considering all the above point, I started the
> http://test.networkupstools.org website, with a consolidated approach. This
> is still a work underway though (or somewhat a failure!)

That doesn't look like a failure to me!  But I think you need to make
a decision about design philosophy.  There are two paths you can go down
with different tradeoffs.

One: Bring the website into the SVN tree as a branch.  (And write a commit
hook that propagates each page to the site whenever it's committed.)

The disadvantage of this approach is that only people with dev access can 
add content to the site.  The advantage is that integration with the in-tree
documentation gets really easy.

This is the approach we use in gpsd.  It is appropriate for a project
with a relatively small, tightly focused developer community and not
much hope that outsiders will ever show up who are qualified to write
docs but not to be core devs.

Two: Make the website a wiki.

This is the direction http://test.networkupstools.org is going, of course.
The advantage is that anyone can write and add NUT documentation.  The 
disadvantage is that the in-tree documentation and the website will be
in different markups, leading to different HTML styles, and there will
be manual labor involved in moving stuff between the in-tree docs and
the wiki or (especially) vice-versa.

This is the approach we use in Battle For Wesnoth, which has a very large
group of outside contributors (artists, campaign developers and so forth)
who neither want nor should have dev access.

Having worked extensively with both approaches, I think the in-tree
one fits NUT's social dynamics better, but I would be willing to do it
the other way if your judgement is otherwise.

> - the final system should fit the above, and allow to be used online (for
> the website) and offline (for the source distribution and packages). It
> should also allow a split between a User Manual, a Developer Manual,
> - your above ASCIIDOC approach seems really interesting (and more than a raw
> docbook approach!) and possibly meeting all the requirement.

Yes, it's a real improvement over DocBook -- almost all the power but
with much lower front-end complexity.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>