[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Making It Easy For New Authors (was Re: Style Guide)
David et al:
> A major problem is that we are making a huge mistake by not having a
> short HOWTO-HOWTO (or the like) that would suggest the use of LinuxDoc
> sgml so as to make writing a HOWTO as easy as possible.
Or DocBook...with a reference perhaps to http://www.docbook.org/
> Contribute/Help document that a prospective author sees first says:
> "Potential volunteers should become familiar with the information
> contained in the LDP Author Guide". This is wrong!
"For a brief introduction to the LDP, please read the LDP-Howto...for an
in-depth guide please read the LDP Author Guide". It sounds like a good
> The Guide,
> although well written, is far too long for many people who want to
> quickly write a HOWTO. It will turn off many potential authors.
That's the perennial problem of all documentation. The man pages are
much more terse but people don't read them :-)
> I think that this problem needs immediate attention and that a new
> author need not understand what a DTD is, what a DSSSL is, etc. I
> wrote a HOWTO without having any idea what these things were. A new
> author that wants to get started quickly should start out with
> another HOWTO in LinuxDoc soruce and then just "fill in the blanks".
> In other words change the name, date, title, paragraph content etc.
Hang on. You could do the same with DocBook XML or SGML.
> I would like to apologize for not saying this earlier. I did argue
> for this previously but not as strongly. I think by continuing this
> we are shooting ourselves in the foot.
By continuing what? This subject?
And so it was that later
As the miller told his tale
That a face that at first was ghostly
Turned a whiter shade of pale....
To UNSUBSCRIBE, email to firstname.lastname@example.org
with a subject of "unsubscribe". Trouble? Contact email@example.com