RE: Blank template

[Gregory Leblanc <GLeblanc@cu-portland.edu>]

> -----Original Message-----
> From: David Merrill [mailto:dcmerrill@mindspring.com]
> Sent: Thursday, June 15, 2000 4:56 AM
> To: ldp-discuss@lists.linuxdoc.org
> Subject: Re: Blank template
> 
> On Thu, 15 Jun 2000, Chuck Dale wrote:
> > > > > So, am I going a good direction with this?  Too many 
> > > > comments?  Too few?
> > > > > 	Greg
> > > > 
> > > > I'm assuming this is aimed at the extreme novice Docbook 
> > > > author; if so, you're
> > > > right to err on the side of overkill. 
> > > 
> > > ok, I'll stick with lots of comments.
> > 
> > Ah I'll throw a paddle back in the other direction: way too many
> > comments. The template needs to be concise to be usable, 
> and some things
> > are overkill. Like this:
> [...]
> 
> I agree with Chuck. I'd rather the template be just that -- a 
> template. No more
> and no less. With the entire text of DocBook: TDG available 
> online, there's an
> excellent reference available to everyone, to explain the 
> meaning of any tag.

Unfortunately, this isn't necessarily available to everyone.  There are
still a good many people who don't have cheap, high bandwidth internet
connections.  I've had several complaints about my not snipping enough in
messages lately for just this reason.  So, I think I will keep this version
of the template with many comments, although I may remove some of the more
pointless ones.  But since my comments are comments, marked by <!-- -->,
they're REALLY easy to strip out.  If somebody doesn't already have
something to do this, I'll write up a script and post it along with the
template.

> I have a bias toward keeping all the documentation together 
> in one document,
> the LDP-Authoring-HOWTO, instead of spread out between there 
> and comments in
> the template(s). I see the template as a kind of "Appendix", 
> or supplemental
> material, to the Authoring-HOWTO. It doesn't need to stand on its own.

I'd have to disagree, sort of.  I recently became a "new" author for the
GDP, and found their layout extremely helpful.  They have a Handbook for
writing GNOME documentation, as well as a number of "templates".  The
templates follow the conventions designated out in the handbook, but can
also be used almost without the handbook.  When I began writing
documentation, I read the handbook, and then grabbed a template, and
"filled" it in.  This gave me a document with structure that was mostly in
line with the other applications (although a bit different, because it is a
non-typical application).  I think that both are needed, but I think the
template is a great starting point for new, and returning, authors.  The
ones with comments can be a good way to get started writing as quickly as
possible, and the completely blank ones can be used by authors who already
know "everything".  Later,
	Greg


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org