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

["Greg Ferguson" <gferg@hoop.timonium.sgi.com>]

On Oct 10,  2:52pm, David Lloyd wrote:
> Subject: Re: Style Guide (was Re: I'm a sucker)
>
> [...]
> > 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

Why is this nebulous? We have a defined mechanism - you have an
idea, propose it to us. Use the LDP Author Guide to assist
in the development of the document (and you can use us as
resources). Submit it to ldp-submit. The document is published.

The part that's missing is a good feedback mechanism from
the consumer (of the content) back to the author. I'm hoping
someone steps up and takes on that task (building the mechanism).

I'd like to hear more of why this appears to be a problem, and I'd
like to help fix it (if I can).


> * 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)

No doubt, but people still know of the LDP. We can do more in that
area, certainly.


> * you're just as likely to receive SPAM on the mailing list as you are
> other conversation

That will be corrected soon. Once debian turns the existing
mailing lists over to us, we will roll all into a closed list
format (you must subscribe to post).

One list will remain "open" for feedback from the web-site,
and for the proposal of ideas for new content pieces, etc.


> > 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.

Yes, and when it was proposed that the LDP define some sort of
order, hierarchy or central contacts (such as a "core team") it
was meant with much resistence. Like you state - it's a fine line.
Perhaps it was in the way it was proposed, I don't know for sure.


> 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.

What is gained by all this, beyond some name recognition? Who benefits,
the LDP or the consumer?


> >  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...

There is no need to create one. This is generated from the
structured content that is provided to us. *No one* needs to create
a TOC. If you see a document within the LDP that *does not* contain
a TOC, please let me know - it is an error.

Style (look) is controlled via the DSSSL. We can tweak that in whatever
way makes sense. Jorge Godoy has been looking into CSS for an
additional layer/way to provide a different look to the LDP documents.
Again, this places no burden whatsoever on the author...they still
provide SGML (or XML).

Please work with us on this. If anyone has ideas on what might
constitute a nice style for the LDP docs, please provide
input. The existing docbook SGML tranformations that were done
can give you an idea of what we currently use for "style" (thru
DSSL). Here are some examples:  Bootdisk-HOWTO, DSL-HOWTO,
Mail-User-HOWTO, Cable-Modem, Program-Library-HOWTO ...to name a few.


> 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?

There are some basic structured elements that need to be included.
If they aren't there, then they are either added (in which case
the corrected document is sent back to the author, with correction),
or the doc is rejected.

Some legacy docs currently part of the archive may not adhere to this.
If they don't, then point them out to me/us.

SGML helps us to enforce a level of structure, our templates help
to provide some *guidance* in the area of how the structure should
be applied. So I believe it comes down to writing style, which I am
(personally) opposed to dictating any sort of rules for.

> 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.

A style guide is present in the LDP Author Guide, and the templates
are available. Strides have been made to assist the authors. We have
a lot of legacy documents that might not follow the guidelines, in
which case we need some assistance to help correct those.

> 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>

Understood. We all feel this way, and the problem will be corrected,
as I stated earlier.

r,

-- 
Greg Ferguson     - s/w engr / mtlhd         | gferg at sgi.com
SGI Tech Pubs     - http://techpubs.sgi.com/ |
Linux Doc Project - http://www.linuxdoc.org/ | gferg at metalab.unc.edu


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org