[Nut-upsdev] Documentation-related questions

[Arnaud Quette]

Hi Eric,

sorry for lagging, we're currently in the process of releasing the new NUT
major release 2.4.0. Adding a few more new Debian packages on my side
(powerman and pwrkap) and some huge Eaton corporate actions and personal
stuffs, and my 48h/day are full...

2009/1/16 Eric S. Raymond <esr at thyrsus.com>

> 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.
>

indeed!


> > - 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<http://www.catb.org/%7Eesr/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!


it was more in the way "the final results are still not there"... and I've
no real non tech people to catch this up.

 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.
>

well, I've thought a bit about that in the past days, and I'm obviously
going for #1 (in-tree).
but I think with a slight variation: a few pieces don't need (and even more,
must not) be in the source tree. This is mostly the Homepage and Protocol
library (== everything not under Documentation in the wiki ; I've started to
reorganize this last with that idea in mind, but it's not finished).
You can have an idea of this by mousing over the wiki menu...

The website is then a base container (homepage + menu) with pointers to the
online documentation.

so I'm thinking about trimming it to that simple base. The wiki may then be
superfluous (I'm hesitating due to i18n, which is another target), and a
static set might do the trick.

we will need to talk / think a bit more to refine the final solution, but
this looks really promising ^_^

> - 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.


indeed, a real breakthrough ;-)

I'll postpone a bit more these discussions to concentrate on the various
mentioned tasks. we can still continue to talk, but I won't be much
responsive atm.

thanks again and cheers,
Arnaud
-- 
Linux / Unix Expert R&D - Eaton - http://www.eaton.com/mgeops
Network UPS Tools (NUT) Project Leader - http://www.networkupstools.org/
Debian Developer - http://people.debian.org/~aquette/
Free Software Developer - http://arnaud.quette.free.fr/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.alioth.debian.org/pipermail/nut-upsdev/attachments/20090120/819806a8/attachment.htm