[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: Blank template
> -----Original Message-----
> From: David Merrill [mailto:[email protected]]
> Sent: Thursday, June 15, 2000 4:56 AM
> To: [email protected]
> 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 [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]