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

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

On Oct 11,  2:15am, David Lloyd wrote:
> Subject: Re: Style Guide (was Re: I'm a sucker)
> [...]
> > 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 template does cover that. Although again, *portions* are
not enforced as strictly as perhaps you'd like to see (given
your comments).

> [...]
> >
> > 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?

The lists were originally setup/hosted with Debian.


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

It's not necessarily feedback just on the web site, it might
be about the content that is available. Should one join a
mailing list to just provide a quick comment? Or to simply
say, "I'd like to start a new HOWTO..."? Maybe they should.
I think I'd would tend to join after I received confirmation
on the proposed HOWTO (as an example).


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

Distrust? Suspicious? Of trying to provide a service back to the linux
community? I feel like I'm part of some conspiracy here. Are we doing
anything right?! :-}

There are a list of volunteers that perform specific functions;
that list is published on the site. Sounds like you want to go
beyond that, so please propose something.


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

Ok, that sounds fine. Although I'm not taking the word "buy" literally.


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

Ok, that wasn't clear from the initial msg. I delved into the
technical aspect of the presentation, based on how you worded
your initial msg (esp w/the toc). I think I know where you are
headed with this.


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

To back up a bit:

1. There is a style guide, it's still being worked on and shaped.

2. Same with the template, which I believe covers some aspects of
   what you want you have brought up (the flow of the document,
   the required structural elements, etc.)

   Earlier I said "There are some basic structured elements that
   need to be included.". That includes authors name, date, version,
   abstract, reference or inclusion of a license, etc.

4. As for technical accuracy, review of content, etc. we need *people*
   to do that function.

   How can we hope to catch something like your examples? No
   level of s/w could handle that; we need people. We would
   need some sort of review board to examine each and every
   submittal and document we have.


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

I'm sorry you feel that way. I have faith this will (finally) get done.




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