Nut upsdev - Jun 2017 - Proposed new documentation "Configuration Examples"

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

Roger

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.

Allow me to suggest a couple more sample configs: 1) Server as UPS controller
with clients that are also on UPS, considering shutdown sequencing and 2) Multi
power supply server with multiple UPS (with or without clients).

- Tim

On June 13, 2017 10:01:54 PM CDT, Charles Lepple <clepple at gmail.com>
wrote:
>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.
>_______________________________________________
>Nut-upsdev mailing list
>Nut-upsdev at lists.alioth.debian.org
>http://lists.alioth.debian.org/cgi-bin/mailman/listinfo/nut-upsdev
-- 
Sent from my Android device with K-9 Mail. Please excuse my brevity.
-------------- next part --------------
An HTML attachment was scrubbed...
URL:
<http://lists.alioth.debian.org/pipermail/nut-upsdev/attachments/20170613/da211da1/attachment.html>

On Tue, 13 Jun 2017, Charles Lepple wrote:
> To be honest, I am not sure that documenting these configurations will 
> reduce the number of questions.
:-)

Hello Charles, I didn't expect such a miracle.  I hope only that it would 
make it easier to answer.

Thanks for your comments; it is clear that I have more work to do.  I will 
reply in detail when the text is more presentable.

Meanwhile, you were kind enough to include a link to my "NUT Setup with 
openSUSE" on page http://networkupstools.org/documentation.html

At the next update, could you change the link to 
http://rogerprice.org/NUT/NUT.html ? Note the extre "/NUT". This will
help
me clean up my pages.  Thanks.

Roger

On Tue, 13 Jun 2017, Charles Lepple wrote:
> On Jun 9, 2017, at 10:16 AM, Roger Price wrote:
>> To address this, I propose a "NUT configuration for Noobs"
which is
>> called "Configuration Examples".
> 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.
Yes, I have used AsciiDoc as part of my failed attempt to add SIGUSR1/2 to 
NUT. That was my second patch. 
https://lists.alioth.debian.org/pipermail/nut-upsdev/2016-July/007204.html 
I generated PDF, HTML, and groff man pages.  I should explain that in my 
past I have done a lot of markup in pre-SGML languages such as groff, SGML 
and it's sub-languages such as HTML, and hundreds of pages of mathematics 
and technical stuff in LaTeX.  I was, for my sins, a member of the SGML 
working group in the ISO, and editor of the International Standard behind 
HTML.  I can markup quickly and accurately, and I find WYSIWYG tools a 
pain and a frustration.

I intended the Configuration Examples as a personal contribution, rather 
than core documentation, so I didn't consider the need for an agreed 
team documentation technique.  My only concern was for readily available 
tools and LaTeX for me fits the bill.

I think that maintenance of the core NUT documentation is a separate 
subject.
> 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.
My choice of A4 landscape with 2 pages per sheet was not very reader 
friendly.  I have generated a second format: A5 with one page per sheet in 
portrait mode.  My PDF viewer is happy to put two pages side by side. 
This is probably the best choice.
> 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.
My problem was that I was using too small a font.  Now that the font is 
bigger, there are just over 80 characters per line, which I claim is 
tolerable for technical documentation.
> 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.
I have reduced the saturation of the colours so that the text will be more 
easily readable.  The colours in the text are very easy to change, but 
diagrams done with xfig need more effort. I'd like to hear from someone 
with the problem what the result looks like, and get some agreement before 
making the changes.
> 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.
Good point, I have removed the references to CHRG and DISCHRG.
> 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.)
Agreed, a LaTeX package was missing and the hyperlinking was broken. 
It's now fixed and fully operational. Table of contents, chapter 
references, line numbers, man pages, external sites and files: all linked 
and clickable.
> 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).
A URL such as http://rogerprice.org/NUT/ConfigExamples.A5.pdf#page.20 
works for Firefox but not Opera. Again with Firefox, 
ConfigExamples.A5.pdf#section.5 and ConfigExamples.A5.pdf#subsection.5.2 
also work, but I cannot get #namedest... to 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.
The "K&R" comes from the Developer's Guide, Ch 3.5 proposal
for an Emacs
function which contains (c-set-style "K&R"). My intention was to
say "This
is real code, lean and mean - not C++ overbloat".  If you prefer I say 
that instead of "K&R", I'm happy to change it.
> 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/... ?
Yes, it should say /etc/systemd/... for user scripts.  I was looking at an 
ancient openSUSE release which is out-of-date.  I have corrected this.

I would like to include specifics from other distributions, but I rely on 
others to volunteer the data.

The updated text is available at 
http://rogerprice.org/NUT/ConfigExamples.A5.pdf

Roger