discuss: LDP Style discussion (cont.)
Subject:
Re: LDP Style discussion (cont.)
From:
Alexander Bartolich ####@####.####
Date:
14 Apr 2002 13:35:27 -0000
Message-Id: <3CB9855C.4060709@gmx.at>
David Merrill wrote:
> Alexander Bartolich wrote:
> > But I really think that if LDP has excessive energy
> > it should invest it into quality control and a usability lab.
>
> [...] This *is* the LDP, a very loosely organized collective.
I consider myself a member of the Linux community.
This makes the LDP a bit _my_ LDP.
> [...] I would be completely surprised if the idea isn't
> supported by all of us, but that won't get it done,
> and the staff are all pretty busy already.
Feeling of being misunderstood I have. ;=?
It's nice if you have the urgent desire to contribute a style
guide. Chances are high that it will make LDP a better place.
But probably you are just searching for any idea to improve
hosted documentation. In that case I have to say that smooth
language is the least thing to worry about.
In some way my insignificant project is only about style.
Restating existing texts in a readable way.
Which leads to my personal list of issues:
1. Make your sentences short.
2 Copy from document templates.
3. Use DocBook. XML is preferred, but SGML will do.
4. Contents must be correct and reproducible.
This includes describing the setup used for
development and all required conditions.
5. Give enough background to let the reader move on
to higher grounds. This will also simplify debugging.
Of course you can dwell on each item and blow it up to a full
science. Let's organize this thing and take all the fun out of it!
But items are sorted by ascending complexity. And IMHO the first
point is not a big problem. I suggest covering that area in a FAQ.
Things like "Should I write 'file system' or 'filesystem'?".
And then provide a series of good templates. With detailed
explanation of the background. At the moment I see the
"LDP Author Guide" and the "HOWTO-template for Big HOWTOs".
And no explanation of the differences between the two.
If everybody used DocBook a DSSSL or a XSLT script could
insert boiler plate texts during rendering. But then
I already said that LDP is really weak on that.
