[Firebird-docs] gsec doc (was: New potential doc writer)

[Paul V. <pa...@vi...>]

Hi Norman,

> I've built a single pdf file and the multipage (defaulthtml) for
> GSEC. I've got it uploaded to a temporary site at
>
> http://www.bountiful.demon.co.uk/firebird/index.html.

Overall, it looks very good! But see some remarks at the bottom
(lengthy as usual...)

> All comments, good or bad gratefully received until the end of this
> week when I'm off to Greece for about 3 weeks :o)

Nice!

> My wife wants some sun, I'll be the one in the shade.
> She won't let me take my laptop, so I won't be updating anything
> after Thursday night this week.

Can't you smuggle it between some shirts? :-)

By the way: which Fb package did you use? I mean, because of the
presence of EPOCMAN. He shouldn't be there, at least not in official
packages.


Greetings,
Paul Vinkenoog


Remarks:

- Yes, good idea to make it a <book>. But you should use <chapter>
  elems instead of <article>s inside. Unlike the "Firebird Database
  Documentation" book, which is a rather loose collection of articles,
  your book's children belong closely together.
  You can leave out <articleinfo/chapterinfo> since you're the
  only author.

- If you show a screen (i.e. a mixture of prompts / user input /
  computer output), use a <screen>, not a <programlisting>. The
  latter is for code fragments, SQL scripts or fragments, etc.

- The screens in the Introduction are very informative, but I think
  you should show them in a later section. Throwing bulky stuff
  in the reader's direction at this early stage may scare them
  out of reading the rest. There are women and children reading this!

  An intro should ideally start with a couple of short paragraphs
  explaining what the tool is all about (like you do), possibly
  followed by an overview of what's to come in the rest of the
  sections (e.g. using itemizedlists or orderedlists).
  After the intro, first some sections about the most common usages
  (again, like you do). But I wouldn't show those lengthy screens and
  look-what-happens-if-you-make-a-mistake examples too early.

  BTW: Maybe you should mention in the intro that on some platforms
  (and depending on the Fb installation package) non-root users may
  not be able to run gsec due to filesystem permissions, regardless
  of whether they know the SYSDBA password or not.

- ids should be all-lowercase: firebird-utilities instead
  of firebird-Utilities; fbutilities-gsec-intro instead of
  FBUtilities-gsec-intro, etc.

- ids should start with the parent id, except when the parent is the
  <set>, or when it is a <book> consisting of <article>s that hang
  only loosely together (like "Firebird Database Documentation").

  Litmus test is probably whether what you write is going to wind up
  in one PDF file. If so, give the top element (the book, in this case)
  an id (e.g. fbutils) and let all child ids start with that:
  fbutils-gsec, fbutils-gsec-intro, fbutils-gbak, fbutils-gbak-restore.

  (Yes, I know I sinned against this principle in the docbuild and
  docwrite howtos! But I was still young then :-) Will probably
  correct it one day)

  You don't have to reflect the entire hierarchy in the id once you
  descend below the sect1 level, otherwise you may wind up with
  outrageous ids like fbutils-gsec-commandline-linux-modify-usernames.
  But set, book, chapter, article and sect1 (or toplevel <section>)
  ids are used to generate the HTML file names, so try to be
  consistent down to and including sect1 level. (And try to keep
  those ids both short and informative.)

-- end-o-remarks --