[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Authorship
Gary Preckshot wrote:
>
> Mark Komarinski wrote:
>
> Mark, you're getting some good feedback from new authors. David Merrill, Joe
> Cooper, and Arnault Claden just told you that they're having real problems
> getting the tools working. These are not old hands, but new authors whose
> feedback is invaluable in determining how useful your howto is to the intended
> audience. I'm just the most vocal of the set.
Careful, Gary, not to speak too boldly in the name of other folks.
I agree that the DocBook tools need better documentation. But I'm not
of the opinion that we need better authoring tools. vi looks great to
me with the lovely syntax highlighting. Fast, familiar, and easy.
All I want from the HOWTO-HOWTO is this:
1. Get the DocBook stuff here.
2. Install it this way.
3. Put this DTD here and do this to make it available.
4. Here's an example of DocBook SGML. Here's a template, too.
5. Type this command to convert your SGML file into these formats.
6. Send the SGML file here so it can be included in the LDP.
7. Thank you for helping the LDP.
I think Mark has very nearly covered that just fine in only one of the
chapters. It's still a little rough...but getting better. The
reference to Godoy's DocBook HOWTO maybe a problem...since that HOWTO is
confusing, to me anyway.
> I don't think it would be a good thing to fragment the HOWTO-HOWTO into a bunch
> of little topical howtos.
> 1) It sends new authors all over the place when they should have "one stop
> shopping".
Ok. I won't argue with that. But make sure it has the steps I listed
above with as little unecessary verbiage as possible.
> 2) It defuses the responsibility for a coherent policy to several squabbling
> authors.
The LDP _is_ a bunch of squabbling authors. No need for it to stop
being that. But the basics ought to be made clear, and respected by
all. The basics, in my mind, being:
- DocBook SGML == Good || LinuxDoc SGML == Ok, but not forever
- Use your favorite text editor, here's a template that we think
represents the right style for LDP docs
- Don't invent your own system of grammar
- Don't try to push your own political/social/computer/business ends via
the LDP
- Be sure to listen to comments from readers and take them to heart the
next time you are revising your document
> 3) It avoids the issues.
What issues?
Either it helps you get started with the tools, or it doesn't. I don't
think there should be any real issues involved. Either you want to
contribute to the LDP, or you don't. If you do, open an editor and
start writing.
The issue of whether DocBook is too complicated for someone, I think,
has already been addressed...Send it in whatever form you can, somebody
will (hopefully) DocBookize it. From then on make your edits to the
DocBook file, or find a DocBook buddy to help you keep it updated.
Everybodies got an opinion on this apparently. I think the HOWTO-HOWTO
is coming along nicely. Mark is doing a fine job. Sure, it needs work,
but don't we all? I don't believe Windows tools should even be
mentioned more than in passing. Sorry, but Linux nerds (the people
knowledgeable enough to write HOWTO's) like working with Linux. I don't
feel at all like Linux is lacking the tools I need to write
documentation. I've written reams of documentation for my companies
products using vi and LinuxDoc.
The notion of catering to Windows users or converting Windows users to
Linux doesn't really seem a worthy goal. Yes, I consulted the HOWTO's
like a bible when I was switching to Linux 2 years ago. But I don't
believe the job of the LDP is to convert people, or to make it easy for
Windows users to clutter up the LDP with irrelevent or ill-informed
HOWTO's.
And that's all I have to say about that.
--
Joe Cooper <joe@swelltech.com>
Affordable Web Caching Proxy Appliances
http://www.swelltech.com
--
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org