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

[Norman D. <No...@Bo...>]

In article <Pin...@s4...>, 
pa...@vi... says...

Hi Paul,

I've reworked the gsec document as per your comments and it is in the 
same place as before :

http://www.bountiful.demon.co.uk/firebird/index.html

The XML is there too.


> > 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!
> 
No, that's in France, I'm off to Crete :o)

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

I'm using 1.5.0.4306 which is probably a late model candidate build. 
I'll download the latest at some point soon. I'm not 'in production' 
with any databases so I'm not too worried yet.

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

It's now a book, with chapters instead of articles, and no articleinfo 
either. It builds ok so I'll continue in theis mode with the rest of the 
commandline stuff.

> - 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.
> 
Done. See new version online.

> - 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!
> 
Women and children are safe again. I've reworked the introduction and 
removed all the scary stuff. It's very gentle now.

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

Sorted. An overview of things to come has been added and scary stuff 
moved down a litle bit.

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

Done.

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

Sorted, I've reduced the size of them too and they are all lower case.

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

Guess what, I've done this as well. :o)

<SNIP>

Thanks for your assistance on my first attempts, hopefully the new 
version meets with 'standards' and I can get on and do some more while I 
still have time (ie Thursday evening !) before my holidays.



Cheers,
Norman.

PS. The start of GBAK has slipped into the pdf and html too, best 
ignored for now - its a very early draft.