editors: Thread: Re: Additional sections (was: Re: Firewall-HOWTO)

On Wed, 2003-11-19 at 11:00, Machtelt Garrels wrote:
> Somebody talked about having a sort of required prereqs section to each 
> document, and then Terrence came up with the idea of an "I want more" 
> section as well.  
> 
> Tabatha, this might be something to put on your list?  I think each 
> document should have both sections in some form, in so far as it is 
> possible.  This will also link our TLDP collection together in a better 
> way.

I liked that idea too, and I'm cc'ing this to the reviewers.  Let's look
out for these, and recommend them in the documentation.  There may some
cases where these might not be useful, but in the majority of HOWTOs and
Guides, I think this can make an author's documentation more robust,
therefore more valuable to readers.

Tab

-- 
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)

On Mon, 2003-11-24 at 22:52, David Lawyer wrote:
> On Thu, Nov 20, 2003 at 02:40:48PM -0800, Tabatha Marshall wrote:
> > I liked that idea too, and I'm cc'ing this to the reviewers.  Let's look
> > out for these, and recommend them in the documentation.  There may some
> > cases where these might not be useful, but in the majority of HOWTOs and
> > Guides, I think this can make an author's documentation more robust,
> > therefore more valuable to readers.
> 
> I don't agree for the case of prerequisites.

In your example of Serial-Programming HOWTO I agree with you.  As you
demonstrated, it's somewhat of an obvious prerequisite (though providing
resources that are related to this document certainly couldn't hurt if
an author was willing).

In obvious cases, no.  Someone might be trying to get a sound card
working though (true story) and find out that in order for their
particular brand to work, they need to know how to change and compile
their kernel for the module.  I might be just a newbie who has no idea
how to compile a kernel, and so stating this is a prerequisite and
providing resource links would be helpful.

An author should use due diligence in assessing whether their subject
matter needs additional references, asking for feedback if they're not
sure.  I would even go so far as to ask both experienced and new Linux
users their opinion.  And I agree, only some (not all) docs should
contain prerequisites.  It certainly isn't a detriment to the doc to
include one, and so perhaps this is just an editorial preference of
mine, falling under my own measure of "a good document."  :D

Tab

-- 
Tabatha Marshall
Web: www.merlinmonroe.com
Linux Documentation Project Review Coordinator (http://www.tldp.org)
Linux Counter Area Manager US:wa (http://counter.li.org)