ServerGuide reviewers needed

[Scott Kitterman]

On Monday, August 22, 2011 08:21:35 AM Ahmed Kamal wrote:
> On 08/21/2011 09:31 PM, Paul Graydon wrote:
> > On 08/17/2011 06:33 AM, Ahmed Kamal wrote:
> >> Hi folks,
> >> 
> >> As you know Adam the maintainer of the serverguide had stepped down.
> >> I'm trying to assemble a team of server oriented folks who are
> >> interested in reviewing the Ubuntu server guide (making sure all the
> >> info inside is fresh and accurate), this is only part of it, the team
> >> would also work on creating a fresh chapter on UbuntuCloud
> >> (openstack+orchestra+Ensemble).
> >> 
> >> If you are interested, please raise your hand
> >> 
> >> Cheers
> > 
> > Hi Ahmed,
> > 
> > Is there a general idea of what level we ought to be aiming the
> > documentation at?  There is a bunch of things that could be added to
> > the MySQL section, for example, without turning it into a full on
> > MySQL Guide (unless that's what we're aiming at?).  Currently it's
> > focussed along the lines of 'this is how you install it, start it and
> > a couple of minor tweaks'.  It could be filled out with brief
> > discussion of the different storage engines provided by the packages,
> > their strengths and weaknesses etc.  The approach seems to vary
> > between different sections of the documentation, and even within the
> > same chapter.  It would seem in general that the database section is
> > woefully lacking in detail compared to other chapters.
> > 
> > Paul
> 
> Hi everyone,
> 
> So I got two questions that I'd like to answer publicly
> 
> 1- What is our deadline
> 2- What is the depth needed for the review
> 
> My answer is
> 
> 1- I'm no docs expert, but I checked and Oneiric "documentation string
> freeze" is Sep 15th. Allowing for 10 days for merge proposal
> discussions, we would have only *two weeks* starting today (22Aug-5Sep)
> to get all the content you would like to review in a "ready to merge"
> state from your perspective. As you can see this is not a lot of time,
> so your prompt help is needed

Documentation string freeze is for documentation shipped in the archive.  A 
few release cycles ago we removed the ubuntu-serverguide package and the guide 
is provided via help.ubuntu.com now, so we should have more time.  That 
doesn't mean people shouldn't start working now, but it's not yet critical.

> 2- Again, since we don't have much time, and since we should not
> re-create upstream documentation, I would try to avoid adding too much
> new content. I would focus this review on only making sure all the
> information in the guide is "correct" and "up-to-date" as of 11.10. This
> would include things like checking package names have not been changed,
> little code snippets actually work...etc. IMO, serverguide should focus
> on the Ubuntu specific parts and not attempt to replace upstream docs,
> with appropriate links to upstream docs
> 
> I understand there's a lot that could be added, however the priority is
> making sure the info is correct and up to date
> 
> Thanks all for the commitment and hard work!
> Keep rocking

Historically we have tried to pick one way to do a task and document that well 
(picking packages in Main over Universe when there is a choice).  For most 
server guide tasks there is more than one way to do it.  We want to pick one 
way that is suitable for relatively inexperienced admins and document it well.

This allows new Ubuntu server users to quickly accomplish common tasks and 
gives us a standard configuration base for support.  

As an example, I still use cyrus-sasl2 for my mail servers, but we made a 
decision awhile back to standarize on dovecot for sasl in the server guide.  
It's easier to set up and we've been standardized on it for many releases.  If 
someone asks about setting up SMTP Auth on #ubuntu-server, I point them to the 
server guide (and dovecot) rather than trying to get them to use my non-
standard configuration.

Scott K