serverguide - couple of comments

[Matthew East]

On Sun, 2006-01-15 at 22:37 +0000, Matthew East wrote:
> Hi all,
> 
> I had a quick look at the serverguide this evening, and reviewed the
> openssh section. It looks pretty good and I've marked it as complete now
> after making a few structural changes, but I have a few minor comments
> based on what I read.

I've now read the preface and introduction and have a few more.

* There was too much complexity in the "Contributing" section. As mpt
said once, the user will read "Docbook XML in a Subversion repository",
go cross-eyed, and stop reading. I've removed this, and made a much
simpler version. The same should be done for the Desktopguide, in fact,
I really think we should be using one preface file for all the docs.
Generally in the preface, simpler language is needed, it's rather
complex right now.
* The preface explains that terminal commands will appear in <screen>
tags, which look nice. But in the rest of the guide, that doesn't happen
AFAICS.
* "Installation" section - I don't think that we need this necessarily:
it doesn't give enough detail to be useful.
* General structure - I think breaking it down into a few more chapters
would be helpful: right now basically everything is in one chapter -
Networking. Can we categorise this any better?

Leaving my other comments (on the Openssh section) below this email.

Matt

>  * Too many words - often the same phrases are repeated and too many
> words are used when few will suffice :) See the styleguide for more on
> this.
>  * Use of wiki resources - Thanks to Bshumate there is a lot of detailed
> material on openssh in the wiki, I think we should be using as much of
> that as possible to give the user greater insight into how the program
> works. At the moment the openssh section (and this will probably apply
> to other sections) is quite short and the user needs more detail for it
> to be really helpful. Either we can copy the wiki material in directly,
> or refer to it, I'm not sure which is best. What are peoples' thoughts? 
>  * [minor] Status tags - no need to give second level sections status
> tags in my opinion. Just chapters and sect1 will suffice, otherwise the
> status reports look a bit confused.

-- 
mdke at ubuntu.com
gnupg pub 1024D/0E6B06FF
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 189 bytes
Desc: This is a digitally signed message part
URL: <https://lists.ubuntu.com/archives/ubuntu-doc/attachments/20060116/569a5fb9/attachment.pgp>