AF:
NF:0
PS:10
SRH:1
SFN:
DSR:
MID:<20090402140154.5ed84a45@ripper.onstor.net>
CFG:
PT:0
S:andy.sharp@onstor.com
RQ:
SSV:mail.onstor.net
NSV:
SSH:
R:<larry.scheer@onstor.com>
MAID:1
X-Sylpheed-Privacy-System:
X-Sylpheed-Sign:0
SCF:#mh/Mailbox/sent
RMID:#imap/andys@onstor.net@exch1.onstor.net/INBOX	0	2779531E7C760D4491C96305019FEEB52AC8BDD804@exch1.onstor.net
X-Sylpheed-End-Special-Headers: 1
Date: Thu, 2 Apr 2009 14:02:24 -0700
From: Andrew Sharp <andy.sharp@onstor.com>
To: Larry Scheer <larry.scheer@onstor.com>
Subject: Re: Some advice about wiki pages
Message-ID: <20090402140224.5f530a0f@ripper.onstor.net>
In-Reply-To: <2779531E7C760D4491C96305019FEEB52AC8BDD804@exch1.onstor.net>
References: <2779531E7C760D4491C96305019FEEB52AC8BDD804@exch1.onstor.net>
Organization: Onstor
X-Mailer: Sylpheed-Claws 2.6.0 (GTK+ 2.8.20; x86_64-pc-linux-gnu)
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit

On Tue, 31 Mar 2009 11:44:14 -0700 Larry Scheer
<larry.scheer@onstor.com> wrote:

> Andy,
>     I would like to get your opinion about writing wiki pages. Should I keep troubleshooting info in the cookbook how-to pages or should I keep the cook-books just that; short concise, how-to docs and break out troubleshooting info into a separate document?
> 
> Take a look at http://wiki.onstor.net/wiki/Leopard:Building_NexentaStor_Packages_from_our_repository when you have time. Let me know if you and others would be better served if the help regarding what to do when something goes wrong  was put in a separate document with links to it in the original how-to guide.


I looked it over, and it looks pretty good as is, although I don't know
what changes you might be contemplating.  In general I guess I would
say that if there is one really common error that might happen at a
particular step, include how to deal with that in the cookbook while
describing that step.  An organized troubleshooting guide that only
talks about that sort of thing should be a parallel document, possibly
with cross references so the same information doesn't have to be typed
in multiple times.  The reader could click on the link to the other
document, read the relevant section, and then hit the [back] button.
There is a way to link directly to sections in the middle of a document
too, so you could take a reader directly to the relevant section.  The
syntax for the link is something like http:wiki_foo#section_title or
some such.

