[Nut-upsdev] NUT Documentation project

[Arnaud Quette]

[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)