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

[Gregory Leblanc <GLeblanc@cu-portland.edu>]

> -----Original Message-----
> From: David Lloyd [mailto:lloy0076@rebel.net.au]
>  
> Hmmm!
> 
> > 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.

I don't follow you here.  What's wrong with the licensing policy?  Why
should feedback on a document HAVE to go to the mailing list?  Sending it to
the author has yielded good results for me.

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

Yeah, but it certainly sounds like you're complaining that we're getting NO
publicity, and not complaining about the bad publicity that we're getting.

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

It's got nothing to do with permission.  Debian was kind enough to host
these mailing lists for us, since we did not have the resources to host them
ourselves.  Now that we have those resources available, we're in the
processor transferring to lists to a new server.

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

For the GNOME website, feedback sent to "webmaster@gnome.org" IS sent to a
mailing list.  Many different people read this, so that they can address
different issues that arise from people emailing webmaster.  The concept for
the LDP is the same.  People will not necessarily join the mailing list if
they have suggestions or comments, they may simply wish to send them off.  A
new author to the LDP should NOT have to be on the LDP-Discuss list, as this
list has quite a bit of traffic, much of which they won't care about while
they're busy drafting their document.

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

Can you rephrase that, it doesn't make sense to me.

> > 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 mailing list runs the LDP.  The people who make policy decisions are the
people who show up here and contribute.  

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

We don't care if they buy it, so long as it's available to them.  I'd like
to see us get better name recognition so that people know where the
documents can be found.  If people choose not to contribute back to the LDP,
that's their decision, we cannot force them to contribute.

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

Your arguments are NOT clear, and you made no mention of that being an
example (that I could see, at least) in your mail.  Have you read the LAG?

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

Maybe you aren't making yourself clear...

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

The LAG has some guidelines for this, and there are a couple of sample
templates, and TONS of sample HOWTOs to go from.  What EXACTLY are you
asking for?

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

Yeah, so what?  We have stylesheets that are designed to do a good job
creating output from the documents that we receive.  The LAG outlines the
things that you should do before you decide to submit your document to 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.
> 
> 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...

No, it's not, for a whole slew of reasons.  Let me quote the LAG for you.

Before you distribute your code to millions of potential readers there are a
few things you should do. 

First, be sure to spell-check your document. Most utilities that you would
use to write SGML have plug-ins to perform a spell check. If not, there's
always the aspell program. 

Second, get someone to review your documentation for comments and factual
correctness. The documentation that is published by the LDP needs to be as
factually correct as possible, as there
are millions of Linux users that may be reading it. If you're part of a
larger mailing list talking about the subject, ask others from the list to
help you out. 


Go read the LAG again, and see if it addresses any of your concerns.

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

This WILL be fixed, as soon as it can be.  As of right now, administrative
control for these lists is out of our hands.  Once it IS within our power,
it will be fixed.  Patience is a virtue.
	Greg


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