Re: Style Guide (was Re: I'm a sucker)

[David Lloyd <lloy0076@rebel.net.au>]

Gregory!

> Right now, the LDP doesn't have all that much respect from much of the Linux
> community.

I have my own thoughts on this matter but it's not entirely the subject
of this particular discussion.

> I'd love to see this change (which is why I'm on the list), but most
> people can't put a finger on what it is that they don't like.

Well, let's see:

* submitting to the LDP is rather nebulous to say the least
* the LDP doesn't "take ownership" of the documents hence its name is
hardly ever heard of (although it seems to be the most reasonable source
for many of the HOWTOs that go with distros)
* you're just as likely to receive SPAM on the mailing list as you are
other conversation

> A lot of people see the LDP as just a big group of individual, without any
> sense of direction at all.  In many respects, this is correct.

It is. What's worse there's no one person, group of "committee" that one
can talk to. The LDP seems to be coordinated by a small group of people
all who participate on the list. In my opinion, the fact that the LDP
manages to pull together some reasonable documentation is despite not
because of its organisation; to put it a little more strongly, the
organisation just isn't there.

Whilst the Linux community and open source community enjoy freedom,
there is a fine line between freedom and anarchy. In Linux major vendors
such as RedHat, SuSe, Mandrake, Debian (who really isn't a vendor but
you know what I mean) provide some type of order within the anarchy of
what is open source.

I believe that we need to pull ourselves together and bring ourselves to
a more consistent touch and feel to the LDP; someone or a group of us
should attempt to convince the vendors not to include the "HOWTOs" but
to include the "HOWTOs by the [author] and the LDP"...a small change but
we're facing a marketing exercise. At some stage many of the HOWTOs have
been submitted to the LDP and we should make sure this is known.

>  I think that
> a style guide, helping to give a more consistent "look and feel" to our
> documentation would go a long ways towards giving the LDP a more
> professional image.

There are some on this list - and possibly some within the nebulous
power structure - who have taken the view that we should not place any
impediments on how people should submit their HOWTOs. Whilst I'm
inclined to agree with this statement in principal, we need to balance
all factors.

For example, what's wrong with convincing people they have to include a
table of contents with their HOWTO? TOCs are devilishly easy to create -
even Microsoft Word has no trouble with them...or they should either
include their contact details or state they don't want to be contacted.
Part of the man pages usefulness is their consistent look and feel; most
man pages are generally quite usable and you can normally expect things
to fall in place. Compare this to the tex-info documents and you'll not
know what you'll find...sometimes something that looks like a man page,
other times just a command option list and at other times an online
manual/tutorial rolled into one.

Both of these approaches have their strengths and weaknesses; we
shouldn't steer away from a more structured "document" simply because
that might frighten some authors away. If the author isn't willing to
include very basic structure in the author's document then do we really
want it? To put this into an example, if we encountered an author who
isn't willing to include an abstract - or allow it to be added - then
what type of person are we dealing with?

Somehow someone or a group of people may need to work out group norms,
some type of style - or no style at all and other matters. 

DL

<gripe>

If I join a mailing list and get SPAMMED by obvious spammers, not just
people who accidentally ask MySQL questions on the PostGres list for
example, then it makes me wonder a few things. Such as "is this list
really professional and who *is* really listening?". "Do I want to cope
with this SPAM?". I don't watch commercial television very much because
of the commercials, despite some of the shows obvious entertainment
value...

</gripe>
-- 
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 ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org