serverguide - couple of comments

[Brian Shumate]

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1

Matt:

I am doing a patch with commands in <screen> to submit for the  
material I have edited.  So far, it has a weird appearance in Yelp,  
but that may very well be due to something I've done wrong- I don't  
know.  In the specific case of the OpenSSH part of ServerGuide, do  
you have some examples of the too many words, and overly repeated  
phrases?

Peace,

Brian Shumate
GPG: 0x441E06C0


On Jan 16, 2006, at 4:08 AM, Matthew East wrote:

> 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
> -- 
> ubuntu-doc mailing list
> ubuntu-doc at lists.ubuntu.com
> http://lists.ubuntu.com/mailman/listinfo/ubuntu-doc

-----BEGIN PGP SIGNATURE-----

iD8DBQFDy7qa43QdCUQeBsARAsGTAJ9oExae6ER3ZiFRK01FY+6FCuxpVQCgvmDW
ZseDVj8oSUcXTwjVv7H3VCo=
=zSf+
-----END PGP SIGNATURE-----