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

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

Hmmm!

> 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 howtos aren't something that most people look for on the net. They
do actually come with distributions (at least until RedHat stopped
distributing them on disk number 1). They looked like they were and are
run by the vendors, not the LDP. This is less than capable marketing.
Surely someone could convince RedHat or SuSe that it's less expensive to
have the LDP document something than write the docs by scratch...

Or are the vendors becoming more and more like the Evil Empire (aka
Microsoft)?

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

You require people to accept licences of varying degrees. Maybe
requiring people to state that feedback should at least be CC'ed to the
LDP would be too difficult...or maybe I'm being sarcastic...I meant
REALISTIC.

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

In what sense? Bad publicity is worse than no publicity.

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

I will believe that when I see it. To be perfectly honest, I *always*
look at those who allow SPAM on mailing lists with suspicion and I only
subscribe to a mailing list that allows spam unless I'm really
interested. I am, believe me, interested in ensuring that the LDP
continues its work and contributes to the community. I'm not interested
in the spam and if you look at my history I've stated so...with voice
and opinion.

Why do you need debian's permission to turn the lists over to you? Have
I read things wrong - is this the Debin Documentation Project?

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

Feedback about the web site goes to webmaster. New ideas and such...if
they're so interted they will join. People who are serious Linux users
will join mailing lists. Maybe you haven't experienced this and I have. 

I will decline to propose new ideas on the "closed list"....this, IN MY
OPINION, is quite silly. There should be one list and one list only.
Let's not go multi-personality....

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

So what we have is an unwritten, unheard of elite group who run the LDP.
Putting it bluntly - and you would know I don't spare feelings or words
- no wonder people distrust the LDP. If you are not capable of forming a
core group then it is natural, even right, that people may be suspicious
of your motives. 

The time for the wonderful touchy-feely is gone. The vendors are here
and they will write their own documentation. There is no doubt about
that...and they can base it on LDP documents - the licence, remembmer,
is generally open content-ed....

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

The LDP and the consumer. Name recognition is important. Most of the
HOWTOS and even man pages included with many distros are based on the
LDP's works or works under its auspices. We all gain if we gain more
recognition....just because we are open source and open content does not
mean we can be null marketing. We MUST market ourselves...people WILL
buy good documentation!

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

I was using an example. I was saying for example, you should give us a
title for your work. Take yourself out of the specifics of my example
and rethink...

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

<sigh>

DSSL and XSL can't translate CDATA without a DTD. There is no DTD for
this e-mail. If I don't provide my name, email address and contact
details how can a DSSL or XSL translation sheet render these fields?
Assuming the LDP decides that it is a good thing to include an abstract
on the content page, how does the DSSL or XSL transaltion sheets render
these fields without the CDATA for the abstract?

You are missing my point entirely.

I'm not talking about style as in physical layout (html, tex, pdf, .doc
or wotever), I'm talking about the way a document is expressed an
formed.

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

Again, you have totally missed my point. I could write you an XSL sheet
for DB 4.1 or 3.1 which rendered DocBook 3.1 in the most inappropriate
manner possible.

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

I wasn't talking about legacy documents. You seem quite willing to talk
about things I hadn't even mentioned.

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

So

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN">
<book>
<title>Using "ls"</title>
<chapter>
<para>
Unless you are a <emphasis>black man</emphasis> or <emphasis>jewish
woman</emphasis> you will already understand what the "ls" command does.
</para>
</chapter>
</book>

Is a valid LDP document. It does conform to DocBook V4.1. I would, of
course fill it out with more racist and sexist comments but ensure its
technical correctness...

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

And Santa Claus can deliver all his presents in one evening...

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