278332 - checksetup.pl needs some documentation in the Bugzilla Guide

Status: NEW

(Bugzilla :: Documentation, defect)

Description

[Shane H. W. Travis]

Checksetup is important; we've got bits and pieces all over saying to be sure 
to run it, but it would be nice to have it amalgamated into one section 
explaining what it is and what it does.

Also, There's nothing in the docs that explains how to run checksetup with a 
script. 

Also, the modifications made to add the --no-silent option (bug 244045) and 
the --help option (bug 256151, which also morphed --no-silent into --verbose) 
need to be documented. This bug is opened for that purpose, 
and 'documentation=?' is removed from those bugs.

Would it be useful to add in the English-language description that Max made in 
bug 277502 at all? Or would that be too much for most users?

Comment 1

[A. Karl Kornel]

I'm in the middle of working on the docs for this bug.  The docs will contain info on checksetup.pl, 
runtests.pl, and sanitycheck.cgi, as runtests & sanitycheck are related to checksetup in that all three 
work to keep a Bugzilla installation running smoothly.  All three are also mentioned in various places, 
but without a single source to which to refer.

To give you a taste of what's to come, I attach a preview.  Everything other than checksetup is ready for 
review, and the high-level structure of the checksetup section is in place.  I'll be asking for reviews from 
documentation@ (for docs structure), mkanat (to verify what I say about sanitycheck.cgi and 
checksetup.pl), and zach (to verify what I say about checksetup.pl and runtests.pl).  I'm also doing this 
to let you know what's coming.

Right now I'm planning on placing this as the last appendix, right before the license at the end of the 
docs.

Comment 2

[A. Karl Kornel]

Attachment: Preview

Comment 3

[A. Karl Kornel]

Attachment: Draft 1

Draft 1.

Requesting review of document structure & formatting from documentation@. 
Colin (or whomever reviews for documentation@), assuming this compiles properly
would you mind attaching the compiled HTML?  Thanks!

Comment 4

[A. Karl Kornel]

Comment on attachment 188457 [details] [diff] [review]
Draft 1

mkanat: Would you mind looking at sections on checksetup.pl (patch file lines
63-527) and sanitycheck.cgi (patch file lines 529-759), making sure that
everything written is correct?	Thanks!

Comment 5

[A. Karl Kornel]

Comment on attachment 188457 [details] [diff] [review]
Draft 1

zach: Would you mind looking at sections on checksetup.pl (patch file lines
63-527) and runtests.pl (patch file lines 761-997), making sure that everything
written is correct?  Thanks!

Comment 6

[Colin Ogilvie [:cso]]

Comment on attachment 188457 [details] [diff] [review]
Draft 1

>Index: Bugzilla-Guide.xml

This is fine...

docs/xml/scripts.xml
>+         <member>User & Group Checks</member>

&amp; instead of &

>+       <title>User & Group Checks</title>

&amp; instead of &

All cases of <varlistitem> and </varlistitem> should be <varlistentry>

>+    <vaiablelist>

<variablelist>

Slightly buggy output is located at
http://landfill.bugzilla.org/bzenumtest/docs/html2/apd.html,
http://landfill.bugzilla.org/bzenumtest/docs/html2/apds02.html and
http://landfill.bugzilla.org/bzenumtest/docs/html2/apds03.html

Comment 7

[A. Karl Kornel]

Attachment: Draft 2

Draft 2

Comment 8

[A. Karl Kornel]

Comment on attachment 188457 [details] [diff] [review]
Draft 1

Moving review requests.

Comment 9

[Max Kanat-Alexander]

Comment on attachment 188467 [details] [diff] [review]
Draft 2

I'll let Zach look over it. If you don't get any response after a week or so,
r? me again.

Comment 10

[Colin Ogilvie [:cso]]

The patch is now valid XML, so I've regenerated the HTML documents above with
the updated patch... now just to read the content etc. which I'll do sometime
earlier in the day.

Comment 11

[A. Karl Kornel]

I'm not going to try for 2.18 on this, just 2.20, although, if the docs end up
being the same for 2.18 and 2.20, I'm not against putting it in both.

Comment 12

[Colin Ogilvie [:cso]]

Comment on attachment 188467 [details] [diff] [review]
Draft 2

>+++ mozilla/webtools/bugzilla/docs/xml/scripts.xml	2005-07-06 17:26:04.000000000 -0400
>@@ -0,0 +1,993 @@
>+<!-- <!DOCTYPE appendix PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> -->
>+<appendix id="scripts" xreflabel="Script Descriptions">
>+  <title>Script Descriptions</title>
>+
>+  <para>
>+    At it's heart, Bugzilla is a complex combination of database tables,

Should it's not be its as it doesn't mean "At it is heart"?

>+    <para>
>+      Weigning in at over 4000 lines of code and comments,

Weigning -> weighing

>+       <para>
>+         <filename>checksetup</filename> now runs through about sixty steps,
>+         looking for files, table columns, and other signs of an old
>+         installation.  Whenever something old is found,
>+         <filename>checksetup</filename> moves the data to its properl place,

properl -> proper

>+         recreates it, or simply deletes it if it is no longer needed.
>+       </para>

Suggestion, which could possibly be a spin-off of this: Document in the
documentation the file thats mentioned within checksetup for unattended
installations.

>+  <section id="scripts-sanitycheck">

>+      As a Bugzilla installation is used, it is possible for inconsistencies to
>+      appear in Bugzilla's database.  These inconsistencies can manifest
>+      themselves as unusual errors, appearing anytime and anywhere.  The
>+      <filename>sanitycheck</filename> script exists to look for these
>+      inconsistencies, reprairing them as they appear (or at least letting you

repraring -> repairing.

>+      know they exist so that you can repair them yourself).
>+    </para>
>+
>+    <note>
>+      <para>
>+        <filename>sanitycheck</filename> is the only script of the three that is
>+        executed through a web browser.  It is executed by logging into the
>+        Bugzilla installation and clicking on the "Sanity Check" link at the
>+        bottom of the page that appears after sucessfully logging in.
>+      </para>
>+      <para>
>+        Another factor that makes <filename>sanitycheck</filename> notably
>+        different than <filename>checksetup</filename> and
>+        <filename>runtests</filename> is the fact that you do not have to be
>+        an administrator to run <filename>sanitycheck</filename>, you just need
>+        to be in the <emphasis>editbugs</emphasis> group.  However, some of the
>+        problems that can be raised by <filename>sanitycheck</filename> may
>+        require adminsitrator access to resolve.

adminsitrator -> administrator

>+      </para>
>+    </note>
>+
>+    <warning>
>+      <para>
>+        Your Bugzilla installation will be unavailable to the world while a
>+        Sanity Check is in progress, so it may not be a good idea to run this
>+        while Bugzilla is in active use (unless you fell you need to).  The

fell -> feel

>+    <para>
>+      Unlike <filename>checksetup</filename> and
>+      <filename>sanitycheck</filename>, there are only a few, well-defined
>+      tests that are performed by <filename>checksetup</filename>, so each can

checksetup -> runtests I think.

>+      be described in relative detail.  Each of these tests are performed
>+      on Perl files or template files.  Each test is executed on all
>+      applicable files before moving on to the next one.  If any test fails on
>+      a file, the failure is logged and the testing continues.  For a detailed
>+      explanation of where the test failed and why, execute
>+      <filename>runtests</filename> with the <emphasis>verbose</emphasis>
>+      option enabled, like this:
>+    </para>
>+
>+    <screen><prompt>bash#</prompt> ./runtests.pl --verbose</screen>
>+
>+    <para>
>+      If you only want to run a specific test, specify the number of the test
>+      (with or without the <emphasis>verbose</emphasis> option):
>+    </para>
>+
>+    <screen><prompt>bash#</prompt> ./runtests.pl --verbose 9</screen>
>+    <screen><prompt>bash#</prompt> ./runtests.pl --verbose 2</screen>

Give an example with and without, please.

Other than that, I think it seems fine... although I would still await a second
opinion.

Comment 13

[A. Karl Kornel]

Attachment: Draft 3

Modification of attachment 188467 [details] [diff] [review], with respect to comment 12 and other things.


I can't believe there isn't an egg-on-face emoticon.  Spelling errors updated
(those listed an the others that I could find).

> Suggestion, which could possibly be a spin-off of this: Document in the
> documentation the file thats mentioned within checksetup for unattended
> installations.

I've added a section on this to the end of the checksetup block.

> checksetup -> runtests I think.

Yup.

> Give an example with and without, please.

Updated.

Also: Added a comma into the title of the sanitycheck section.	Also moved the
credit note one para down and created a caution regarding who can execute
checksetup.  There were also a few one-word and one-sentence changes.

Requesting review from documentation@.	Moving other review requests to this
bug.

Comment 14

[A. Karl Kornel]

Comment on attachment 189213 [details] [diff] [review]
Draft 3

mkanat: Would you mind looking at sections on checksetup.pl (patch file lines
63-962) and sanitycheck.cgi (patch file lines 964-1194), making sure that
everything written is correct?	Thanks!

Comment 15

[A. Karl Kornel]

Comment on attachment 189213 [details] [diff] [review]
Draft 3

zach: Would you mind looking at sections on checksetup.pl (patch file lines
63-962) and runtests.pl (patch file lines 1196-1433), making sure that
everything written is correct?	Thanks!

Comment 16

[Max Kanat-Alexander]

Comment on attachment 189213 [details] [diff] [review]
Draft 3

From what I read it seems accurate, but also too long. That is, some of the
information is info that only developers would like to know, and some of it is
stuff that admins would like to know. Admins mostly want to know when and why
they run the script, and a few brief sentences on what the script does.

They'd probably also like to know about the --help switch.

Comment 17

[A. Karl Kornel]

Comment on attachment 189213 [details] [diff] [review]
Draft 3

LpSolit: Would you mind looking at sections on sanitycheck.cgi (patch file
lines 964-1194), making sure that everything written is correct?  Thanks!

Comment 18

[Zach Lipton [:zach]]

(In reply to comment #16)
> (From update of attachment 189213 [details] [diff] [review] [edit])
> From what I read it seems accurate, but also too long. That is, some of the
> information is info that only developers would like to know, and some of it is
> stuff that admins would like to know. 

I agree with Max here. This is great work and incredibly helpful to have such
well documented, but I think it should be split to avoid overloading admins with
too much information: 

* A brief description of each script, targeted at admins, with a focus on
"here's what it does, here's how to use it." This should go in the Guide like
you were planning. 

* More detailed documentation (e.g. all the great material you already wrote).
This should go in the Developers Guide, where it can be of use to future
developers. 

Thanks for all your work on this!

Comment 19

[A. Karl Kornel]

(In reply to comment #16)
> From what I read it seems accurate, but also too long. That is, some of the
> information is info that only developers would like to know, and some of it is
> stuff that admins would like to know. Admins mostly want to know when and why
> they run the script, and a few brief sentences on what the script does.

(quoting from comment #0)
> Checksetup is important; we've got bits and pieces all over saying to be sure 
> to run it, but it would be nice to have it amalgamated into one section 
> explaining what it is and what it does.
> 
> Also, There's nothing in the docs that explains how to run checksetup with a 
> script. 

Documenting what it is and what it does could be compressed into a few sentences, especially when 
trying to convey the importance of not running until the proper time when doing an upgrade.  

Explaining how to run checksetup with a script also could not be compressed, as neither the source 
code nor the comments of checksetup provide a complete list of various keys of $answer that 
checksetup uses.  If there was more detail in checksetup then the docs could simply refer to that ("see 
lines 123-456 for details on $answer and the list of keys that are used").

Comment 20

[A. Karl Kornel]

(In reply to comment #18)
> I agree with Max here. This is great work and incredibly helpful to have such
> well documented, but I think it should be split to avoid overloading admins with
> too much information: 

Although I can't claim professional experience on this, personally I would have preferred having 
documentation like this for certain Bugzilla scripts, rather than having to read through the code itself, 
many portions of which can be virtually unreadable to someone with only novice-level Perl experience.  

It might be a good idea to put a warning into future release notes, stating that full and proper 
understanding of Bugzilla by maintainers can only be attained by users who have advanced knowledge 
of Perl, with moderate knowledge of related technologies (DBI, SQL, TT, etc.).

> * A brief description of each script, targeted at admins, with a focus on
> "here's what it does, here's how to use it." This should go in the Guide like
> you were planning. 

As I said in comment #19, this could NOT be compressed as well as people might expect (notice the 
word NOT, which is accidentally absent from its proper place in comment #19).

> * More detailed documentation (e.g. all the great material you already wrote).
> This should go in the Developers Guide, where it can be of use to future
> developers. 

I can see two problems with this.

The first problem is location.  I can see no location within the developer's guide for documentation such 
as this.  Quoting from said guide: "The following is a guide for developers about getting your code into  
Bugzilla."  This documentation would give aspiring developers an overview of what checksetup.pl, 
runtests.pl, and sanitycheck.cgi do, without delving into the details that said developers would need.  
The checksetup.pl docs I wrote may even work against them, as someone reading them for the first 
time may get the idea that the actions performed by checksetup are broken up into various well-
delineated groups, ignoring (or not completely heeding) the warning I wrote saying that the opposite is 
true.

The developer's guide reads to me as a style guide, a list of things that you should and should not do if 
you want your code to pass review.  Including information about specific files may set a dangerous 
precedent.  If these files are included, why not others?  When should you stop?  How detailed should 
you be?

The second problem is maintenance.  Quoting from the documentor's guide: "Often the fact that the 
person writing the docs doesn't already know how the feature works results in better documentation 
because of the documentor having to quiz the developer on how it works, and being able to present it 
in a "less technical" way."  Right now I know of no procedure for easily extracting information on 
features & scripts by going through the developers.  If I look at the bugs that have documentation? set, 
I would prefer to see a comment or two from the assignee (or patch author), addressed to the 
documenter, saying what the new features are.  I have found instances of this to be very rare.

There are already enough unresolved documentation bugs.  By adding something like this to the 
developer's guide, you would have to keep it up-to-date with every release, putting even more pressure 
on the documentation team (unless you want to get the developers to maintain this documentation).  
Failing to completely update it for every release would discredit it, possibly sending people directly to 
poring over the source code.

Finally, I should note that this is NOT detailed documentation.  Detailed documentation, the kind that I 
would want if I was doing lots of work to checksetup, would include descriptions of every subroutine 
and the reason behind every action checksetup takes, along with additional information that I do not 
list here.

> Thanks for all your work on this!

You're welcome!

Comment 21

[Max Kanat-Alexander]

You can make a new section in the dev guide, or move some of these things to
comments/pod docs for checksetup.

The docs are too long as they stand now, they need to be more concise. Admins
are looking for a very brief description of the practical application of things.
They don't have a lot of time to read long documentation.

Also, usability studies show that people scan web pages, not read them. So
things that can be easily scanned are better than long descriptions.

Comment 22

[A. Karl Kornel]

Based on comments received in recent days, it seems that this bug should probably not have been 
confirmed with its current summary description.

(quoting from comment #0)
> Checksetup is important; we've got bits and pieces all over saying to be sure 
> to run it, but it would be nice to have it amalgamated into one section 
> explaining what it is and what it does.

When I hear section, I think of lots of information.  It turned out that lots of information was too much.

> Also, There's nothing in the docs that explains how to run checksetup with a 
> script. 

I do not think that this could be adequately covered in a few paragraphs.  There is no complete list of 
$answer keys available short of going through all of the code.

> Also, the modifications made to add the --no-silent option (bug 244045) and 
> the --help option (bug 256151, which also morphed --no-silent into --verbose) 
> need to be documented. This bug is opened for that purpose, 
> and 'documentation=?' is removed from those bugs.

--help could be referenced, but --help alone, or --help plus a paragraph, may not be enough for a 
good description, as --help has a number of points that aren't fully discussed anywhere (i.e. why is -t 
so dangerous that it warrants "use at your own risk"?).  --help alone certainly isn't enough for 
descriptions of SCRIPT, --verbose, and how to automate (where is a list of all the questions checksetup 
asks?  Does %answer have to be declared in the file, or is it already done?  what do you mean by "output 
results of SCRIPT being processed", does it produce more info than running checksetup without a 
script?).

> Would it be useful to add in the English-language description that Max made in 
> bug 277502 at all? Or would that be too much for most users?

I agree the complete description would have been too much, but apparently condensing it was also too 
much.

Some additional comments:

I noticed one thing missing from the documentor's guide: The target audience.  What does everyone 
want the Bugzilla documentation to be?  Do people want it to be a couple of pages long, such as the 
quick-start guides that you seem to find with boxed software these days?  Or, do people (such as 
myself) want it to be like a Missing Manual, where Dreamweaver MX is covered over 792 pages, home 
networking gets 264 pages, excel gets 792, XP Home Edition gets 694, and Office gets 752 pages).  Go 
to http://www.missingmanuals.com/about.html and read about why the series exists and what makes a 
Missing Manual.  In my mind, Bugzilla exists on the same footing as products from Adobe, Macromedia, 
Apple, etc, with new features being added and changed regularly.  Although the software doesn't cost 
$300 to obtain, how much money is spent in customization and setup, and how much could be saved if 
the people doing the work had a Missing Manual for Bugzilla, instead of having to go through the 
source code itself?

Apologies for the rant.  I guess I failed in two ways here.  First, I failed to grasp the actual expected 
length of the requested documentation.  Second, I failed to understand the target audience for the 
documentation.

As the assignee of the bug, I'm marking this as WONTFIX.  Either (a) one bug should not be used to 
cover different modifications to different files, as suggested by comment #18.  Or (b) if changes are 
only being made to the Bugzilla docs, the requirements should be laid out more clearly.  Instead of 
words like "section", a comparison with a current section, or a paragraph count would be nice (i.e. 
"need several paragraphs on checksetup, when to use and basically what it does").  Feel free to take the 
documentation I've already written, but be gentle to it.  I probably spent as much time on those 
attachments as others have spent on like-sized changes to code (though of course that can vary 
widely).

Comment 23

[Max Kanat-Alexander]

Section means just section. It can be large or small. checksetup is a small part
of Bugzilla, so the docs should be small.

How to run checksetup with an answers file is practically entirely described in
checksetup.pl itself, as I recall. Two paragraphs max (and maybe one example)
should do it, I'd imagine. Perhaps even one.

If you think --help is unclear, we can also patch that.

What checksetup *does* can be condensed into a very short 1,2,3 list -- details
could go in checksetup itself as comments.

The target audience is Bugzilla admins.

I do appreciate all your documentation work on that patch. I'd like to see a lot
of that in various places. Just not all of it in the Bugzilla Guide.

All that said, checksetup does need a entry in the docs somewhere. Perhaps not a
chapter, but at least a section. (Section meaning "a piece of greater or lesser
size.")

Comment 24

[A. Karl Kornel]

mkanat: You seem to know exactly what you want to see out of this.  You have the
bulk material in the form of Draft 3.  I leave it to you to take that and create
the docs you are looking for.  If you don't want to do it, please reassign the
bug to the default owner for the Documentation component.

Comment 25

[Zach Lipton [:zach]]

Max: do you mind if I take this one? 

I think all the pieces here are good and certainly too good to throw away, but
I'd like to do some massaging to fit it more closely in with our existing
documentation. 

Comment 26

[Max Kanat-Alexander]

Hey Zach. No, I sure don't mind at all! :-)

Comment 27

[Frédéric Buclin]

Bugzilla 2.20 is no longer supported. Retargetting to 2.22.

Comment 28

[Frédéric Buclin]

Bugzilla 2.22 is no longer supported.