Submission: Home Server Setup Guide

Karsten Wade kwade at redhat.com
Mon Sep 5 20:45:34 UTC 2005


On Sat, 2005-09-03 at 07:30 +0400, Miles Brennan wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> G'day to all,

G'day.  Nice, long holiday weekend here in the States, just getting
around to some email. :)

> As Karsten queried a few weeks earlier, yes I’m one of those lurking,
> too busy at the moment, don't know where to begin, never used CVS and
> not sure what to do - classic post and you caught me out ;)

Excellent.  Glad we drew you out. 

> Over the new year break I wrote the 'Linux Home Server HOWTO'
> (http://www.brennan.id.au).

I haven't read all the way through, so this is a preliminary overview.

0. Thank you for bringing this here, we are very interested in working
with you to get this into Fedora Documentation.

1. Great work.  Very useful.  Covers -lots- of common topics we have no
documentation for.  This project will benefit greatly from the inclusion
of this guide.

2. A small book this size would benefit from more help; I'd be concerned
that maintenance by yourself would be tiring.  Recruit help? 

3. Fedora docs focuses on solutions found only in Core and Extras; if
there are solutions you choose outside of those, we would want them
changed to Fedora-only solutions.  We can reference other solutions in a
stand-alone chapter, if you don't want to totally kill the content.  I
haven't finished reading through yet, so I have no examples, _if_ they
exist.

4. Small style changes, throughout.  For example, consistent use of the
active ("Click OK and a dialog opens") v. passive ("When you click on
OK, then a dialog will open").  We like the active voice, it engages the
reader with what they actually experience.  We expect most folks to do
the task with the documentation present, so what they see is not what
they -will- see but what the -are- seeing. ;-D

Another example is changing the pronouns from first-person plural ("we")
to second-person singular/plural ("you").  I'll be happy to explain
these style choices further, if anyone needs.

> It is a complete HOWTO for setting up a Linux gateway server connected
> to the Internet and providing network resources to the internal
> workstations (MS/Linux). Firewall/Samba/DNS/NTP/FTP guides etc...
> 
> It was originally written for FC3 so some of it may need a little
> tweaking as I haven't yet updated it. However it is a complete HOWTO, 20
> chapters in all (~180 pages when printed).

IMO, this is more of a guide than a how-to.   It's definitely in the
how-to format, but it is really a full length book/guide.  Once it has
chapters, it's a book. :)

> I now offer it for comment / criticism / appraisal / submission.

What do you want to do:

1. Maintain sole authorship, under the FDP
2. Lead a team of writers, under the FDP
3. Toss over the wall to the FDP, let us recruit writers and editors to
continue your work

Option 3 is the one we try to avoid.  I recommend option 2.  It keeps
you in charge of the document, as the lead writer.

As for the CVS parts, that is much easier than you think.  Easier than
learning to use DocBook, and much easier than the concepts you cover in
this guide. 

A first step is to work with an editor to convert the guide to use the
FDP DocBook template and style.  The we can publish it for FC3.  We can
also recruit interested writers to work on sections to update to FC4,
unless you are able to do that yourself.

> I would prefer to keep the content / concept complete if possible, but
> open to suggestions.

Content and concept are easy to keep together.  Normally, we would have
written up each chapter as a stand-alone document, then tie them all
together.  This comes prepackaged, which is fantastic.  Our only changes
would be minor formatting via the stylesheets and XML choices we make,
and writing style.

The latter, btw, focuses partially on making it easier to translate by
reducing idioms, etc.

> BTW, hello list :)

Hello!  Welcome, this was quite a nice self-introduction.

- Karsten
-- 
Karsten Wade, RHCE * Sr. Tech Writer * http://people.redhat.com/kwade/
gpg fingerprint:  2680 DBFD D968 3141 0115    5F1B D992 0E06 AD0E 0C41   
                       Red Hat SELinux Guide
http://www.redhat.com/docs/manuals/enterprise/RHEL-4-Manual/selinux-guide/
-------------- 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: <http://listman.redhat.com/archives/fedora-docs-list/attachments/20050905/ffa24bd4/attachment.sig>


More information about the fedora-docs-list mailing list