[Nut-upsdev] Proposed new documentation "Configuration Examples"

[Charles Lepple]

On Jun 9, 2017, at 10:16 AM, Roger Price wrote:
> 
> Most of the questions asked in the nut-user mailing list seem to me to be either erudite technical discussion of new and exotic UPS units, or n00b questions of the style "I have this old UPS so I installed NUT but it didn't work".
> 
> NUT is thoroughly documented with man pages and User Manual, but from my own experience it is not easy for Joe N00b to know what a working setup should look like in his case.

To be honest, I am not sure that documenting these configurations will reduce the number of questions. Many people have preconceived notions of what NUT should do, based on what their current OS or vendor-provided software does (e.g. shut down after N minutes on battery). Perhaps the solution is to help map their configurations to NUT equivalents?

> To address this, I propose a "NUT configuration for Noobs" which is called "Configuration Examples".  A 27 page PDF file formatted to be read on a 17 inch or bigger monitor using for example muPDF or evince.  It could be printed, but fewer people have printers these days.
> 
> The configurations are:
> 
> 1. Simple server with no local users
> 2. Workstation with local users (solves the wall problem)
> 3. Workstations share a UPS
> 4. Workstation with a heartbeat
> 5. Workstation with timed shutdown
> 6. Workstation with additional equipment
> 
> The first version is at http://rogerprice.org/NUT/ConfigExamples.pdf Before I announce this in the nut-user mailing list, any comments, especially on the choice of configurations, are very welcome.

Before I get into specifics, I would like to mention that there is a lot of useful content in this document, and it seems like a good companion to the NUT documentation.

With that in mind, please understand that this criticism is meant to be constructive, although I do not have ready answers for all of these points.

I agree that printers are becoming less and less common. However, I am not sure that a two-column format with little space and no rule between the columns is the best choice for screen display. Many PDF viewers can display two pages side-by-side, and will do so with a dark border around each page. There is probably a middle ground between these dimensions and the ones used in the AsciiDoc-generated PDFs.

There are recommendations out there concerning maximum line lengths for readability, and I think they are closer to 65 characters. The 90-100 character lines seem to me to be harder to read, especially with the close column spacing.

I think color can be useful in diagrams, but it can be distracting in running text. Also, red/green colorblindness is probably common enough to consider choosing another color for either upsd or upsmon.

The CHRG and DISCHRG status flags are probably confusing for an entry-level text, and are more informational than the critical OL/OB/LB flags. Some models do not indicate CHRG or DISCHRG, and others will omit CHRG if they are OL but not topping off the battery.

On page 5 (right column), it mentions that /usr/lib/systemd/system-shutdown is for user scripts, and /lib/systemd/system-shutdown is for system scripts. Should the first be /etc/systemd/... or /usr/local/systemd/... ?

You have probably noticed that I often link to a specific section of the NUT HTML documentation. I appreciate that you have written this in a tutorial format rather than as a reference, but you may still need to point users to a specific location, and page numbers are not stable over time (and neither are section numbers).

Also, some of the internal references to lines and sections do not seem to be links. (This might be my web browser and PDF reader combination, but usually the table-of-contents links work.)

The last one is a bit pedantic, but the K&R format of the source code is probably not important enough to mention in the introduction. Usually "K&R" refers to code that will not compile without adjustment in a C89-compliant (or later) compiler.

I am also curious whether you tried to edit any of the existing NUT documentation before creating a new document. We chose AsciiDoc in part because it should not be as much of a burden as other markup formats to read or write, and because it offers several output formats. If it turns out to be a deterrent to contributions, that is something we should address. I am concerned about the maintainability of several documents going forward, and I (selfishly, perhaps) would appreciate more help on the core NUT documentation. Your thoughts on this would be appreciated.