Nut upsdev - Jun 2007 - NUT Documentation project

[was: Asking hard questions about the NUT architecture]

Hy Eric,

2007/5/31, Eric S. Raymond <esr at thyrsus.com>:
> Arnaud Quette <aquette.dev at gmail.com>:
> > doc definitely!
> > As mentioned earlier, I've tried several times to start a full
> > rewrite, using docbook, to produce a friendly and complete html doc.
> > But the facts are that the doc writers have gone away, and the major
> > upcoming changes would have lead to far too many doc update...
> >
> > If you're interested in that, I can give more details.
>
> Yes, I'm interested.  Don't know if you're aware of this, but
I'm an
> expert at DocBook and the associated tools.  Overhauling your documentation
> infrastructure is something I could do relatively qickly and easily.
great.

you can find some info on the previous attempt on alioth (task section):
http://alioth.debian.org/pm/task.php?group_project_id=40&group_id=30602&func=browse
http://opensource.mgeups.com/projects/nut-doc/

You'll find there the attempt to convert the doc/ directory (plain txt
file) to a structured docbook base. But it's outdated (based upon nut
1.4 files), and need some more in depth changes and update of the
content.

The various aims of this sub project are:
- to consolidate the various information scattered between nut/doc/,
the website, and the not yet written content,
- to have a doc system that allow easy maintenance / update (like
wysiwyg, using ooo2dbk / wiki systems, ...)
- to split the doc into a User and a Developer Guides
- maybe to create a quickstart guide (very simple, ie 2/3 pages, only
addressing the basic things and pointing the full User Guide
otherwise)
- to use the html generated for the website,

Some more notes:
- we will have to emphasize on HAL,
- we will also have to prepare the field for the nut configuration
tool/lib (that will greatly improve the configuration process...)
- the file attached is a draft of the chapters re ordering, and few thoughts.

I let you check all that, and get back with questions, thoughts and comments

Thanks again for your help on this point.
Arnaud
-- 
Linux / Unix Expert - MGE UPS SYSTEMS - R&D Dpt
Network UPS Tools (NUT) Project Leader - http://www.networkupstools.org/
Debian Developer - http://people.debian.org/~aquette/
OpenSource Developer - http://arnaud.quette.free.fr/
-------------- next part --------------


1) re arange chapters and split these into a User and a Developer Guides
======================================================================
General notes:
- html will be the privileged format (along with plain txt if we can generate
something close to the current things)
- add the NUT logo in the doc's header

User Guide: 
-----------
1/ README
	+ features (http://eu1.networkupstools.org/features/index.html)
2/ INSTALL
	=> from source
		8/ configure
	=> add from packages
3/ UPGRADING
7/ config-files
	4/ big-server
	10/ data-room
	- add a note about configuration GUIs:
	http://cvs.mandriva.com/cgi-bin/cvsweb.cgi/gi/perl-install/standalone/drakups
	http://www.alo.cz/knutsetting/index-en.html

?? ... Using NUT 
	- add a note about GUIs (+appendix)	
	20/ shutdown
	?? ...
		24/ upssched
		17/ pager
		16/ osd-notify => merge with pager...
?? ...
	9/ contact-closure
	21/ snmp
	?? USB
?? Security
	23/ ssl
	5/ chroot

+ Appendix: 
	- compat list (http://eu1.networkupstools.org/compat/stable.html), generated
from nut/data/driver.list
	- cables (from http://eu1.networkupstools.org/cables/)


Developer Guide: 
----------------
11/ design
12/ developers
6/ commands
14/ new-drivers.
=> + extending drivers
	Basic serial
	USB
	SNMP
	... fenton, megatec, ...
15/ new-names
19/ protocol
=> + new clients

13/ ideas => TODO list
+ nut-ng (HAL changes)

18/ powersaving
22/ sock-protocol

2) update from patch-nut-doc.diff (update from 1.4 to 2.x)
=========================================================
3) Write a doc maintainance procedure
====================================(wysiwyg if possible, ie using ooo2dbk?
http://linuxfr.org/2005/01/07/18017.html)

Arnaud Quette <aquette.dev at gmail.com>:
> The various aims of this sub project are:
> - to consolidate the various information scattered between nut/doc/,
> the website, and the not yet written content,
> - to have a doc system that allow easy maintenance / update (like
> wysiwyg, using ooo2dbk / wiki systems, ...)
> - to split the doc into a User and a Developer Guides
> - maybe to create a quickstart guide (very simple, ie 2/3 pages, only
> addressing the basic things and pointing the full User Guide
> otherwise)
> - to use the html generated for the website,
> 
> Some more notes:
> - we will have to emphasize on HAL,
> - we will also have to prepare the field for the nut configuration
> tool/lib (that will greatly improve the configuration process...)
> - the file attached is a draft of the chapters re ordering, and few 
> thoughts.
> 
> I let you check all that, and get back with questions, thoughts and
comments
None of this is difficult, except for WYSIWYG -- there aren't really
any good WYSIWYG DocBook editors yet.  Nor, to my knowledge, is
there a wiki-markup-to-DocBook translator.

I could budget time for a DocBook up-conversion of your existing
stuff, and a reorg/edit pass, late next week.  This will happen
quickly, as I have good tools and a *lot* of relevant experience -- I
think three or four days of concentrated work will do most of it.  You
can get a good idea of what to expect as results by looking at the 
gpsd website and white papers: <http://gpsd.berlios.de/>.

I don't want to do this while you're in final pre-release mode, though
-- it would be better if the dev group could review my changes at
leisure rather than having a fait accompli thrown at them at the last
minute.  You should ship *before* I start serious work and plan on a
point release in another month or so specifically to get the new
documentation on the street.

I'll need commit access to the repo and write access to the website.  
I'm now esr-guest on alioth.
-- 
		<a href="http://www.catb.org/~esr/">Eric S. Raymond</a>