RE: Authorship

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

First, let me say that about 85% of this makes ZERO sense to me, since I
don't know what ANY of the suggested changes were/are.  See some more
comments below.

> -----Original Message-----
> From: Gary Preckshot [mailto:garrell@inreach.com]
> Sent: Tuesday, May 30, 2000 4:37 PM
> To: LDP
> Subject: Authorship
> 
[snip]
> I'm trying to move that into appendices with references to 
> the appendix in the body.
> <Link> works fairly well. 

That's way to vague for the LDP discuss list, might make sense to Mark.

[snip]
> 1)  SGML tools are far and few between.  We're lucky that any work.
> 
> I agree with that. All the more reason for giving guidance to 
> prospective authors
> for sorting out combinations that work in their situation. 
> One of the things I
> discovered is that it was really difficult to figure out what 
> was happening where.
> One of the things I tried to do is sort out combinations that 
> worked. If we're going
> to ask authors to use SGML, we should not set them an 
> impossible problem or give
> them incomplete guidance.

ARGH.  :-)  We REALLY need to get processing tools available to authors on
some machine that the LDP is in charge of, probably through a web form.  It
would be REALLY nice to not have to have people worry about this.  

> >2)  Not many other platforms that support the tools we use.
> 
> Well, a combination of Windows NT and Linux does - QED. Why else LILO?
> 
> >3)  The "original" (my) version listed that 1.0.9 was for LinuxDoc
> and was called sgmltools.  The 2.x version works with DocBook
> and is called sgml-tools.  Both are not being updated anymore and
> should be removed in favor of sgmltools-lite or doing it by hand.
> 
> So why have in the HOWTO?

SGMLtools 1.0.x series is being maintained.  I've got mixed feelings about
the sgmltools-lite (especially the name).  There are also the Cygnus Docbook
tools.  http://sourceware.cygnus.com/  I think.  There should/will be newer
versions before too long.

[whole series of incomprehensible stuff snipped]

> >"FAQs about the LDP"

More importantly, the LDP FAQ?  I've been thinking about this for a while,
but I don't have a list of questions.  Answers should be easy to come by.
So, anybody who's got a good feel for the recent questions feel free to post
them in another thread, and I'll take them and put them with answers in a
document.  

> >1)  Usually that's just a pointer to the ldp-discuss list.
> 
> But there wasn't any pointer.
> 
> >"Configuration Management"
> 
> >Woah.  I wouldn't call CVS this a configuration manager.  
> It's not.  It's source
> >code control.
> 
> Which is configuration management for software or documents. 
> I think probably
> there's confusion as to why LDP is using CVS. If we're not 
> using it for
> configuration management, then why are we wasting time and resources.

Can you define "configuration management".  That's like me saying to the VP
of our company, "we need RAID".  He's going to ask about termites, or
cockroaches or something.  

> >2)  Not sure what you mean by this.
> 
> The confusion over configuration management makes that 
> obvious. Why is LDP using
> CVS? Because somebody said we should? Bad reason. If you 
> can't state the policy,
> then there is no policy.

There is a policy.  CVS is there to allow us to better track and maintain
our documents, and the scripts that we use, and other administrivia.  Just
because one author isn't clear on the policy doesn't mean that the LDP as a
group doesn't have one.  If you feel that things are relavent to the list,
send them here please.

> >3)  LDP doesn't write the software.  It's not to our 
> advantage to maintain older
> tools on the CVS site.
> 
> After calling SGML "code" numerous times, you say this?

I think this is just not being quite clear enough.  The LDP does not write
Software Applications.  The LDP does write software documentation.  This is
code because of the markup we use to give those words added meaning.
Assuming that you're talking about the SGML Tools projects, we DO NOT
maintain those, although we are the primary target users.  The SGML tools
1.0.x has a site on SourceForge (I believe).  The DocBook specific SGMLTools
v2 and v3 have a site on SourceForge.  No need for us to host software when
there are FAR superior alternatives for that sort of thing than our time on
Metalab and Serek's PLD server.

> What's really obvious is
> that LDP is asking authors to produce writing to certain 
> format standards, and it
> has no control over the tools it recommends in its own HOWTO 
> about writing HOWTOs.

That's only partly true.  We have as much control over those tools as
anybody else who doesn't write their own tools.  The LDP is not a project
with the size and power of the Linux Kernel, or the GNOME project.  We've
got volunteers to write docs, we don't have dozens of people coding for us
(although that would be nice).  We can only ask for what we want, until we
come up with some programmers.  I'm going back to school in a few weeks
(along with working full time) so that I can get back into programming, and
maybe helping out a bit.  

> Not only that, you've just told me that the version currently 
> on the LDP web site is
> way out of date, and was when it was written. If ever there 
> was a case for
> configuration management, this is it.

The current version of what?  Elaborate please.

> >4)  I list the reasons really along with the reasons why CVS 
> is good.  The
> biggest advantage is the goal of having LDP documentation 
> automatically updated
> and distributed after a CVS update.  Alas, it's not in place (yet)
> 
> It isn't why CVS is good. CVS is just a tool. It's the LDP 
> policy that counts here.
> Otherwise you end up having your horizons defined by a tool. 
> Dare I say it? This is
> a prime example of geekthink. You have a problem, find a tool 
> that sort of does some
> useful stuff, lose sight of the problem, and wander among the 
> trees of CVS. The
> logic should be:
> 
> LDP wants to accomplish a), b), .... z). It has decided to 
> use CVS to accomplish the
> d), h)....and r) goals. Here's what LDP gets out of it:....  
> Here's what you get out
> of it:... Here are the steps to use the LDP CVS server:... 
> Here's what you need to
> accomplish those steps:.....

We've got the goals, and some ideas on how to use CVS to accomplish those
goals.  Most of these ideas are stored in the heads of some of the people
who have been here for a while, and we're a bit lax on communicating with
Mark, and the LDP list in general, about what we're doing.  We'll get there,
and maybe we can write some more on that.  However, I think it should
probably go on the CVS list, so that the people who are really interested in
that can keep track, and we don't clutter up this list.  I think Mark has
some info about that in the HOWTO-HOWTO, so subscribe and take this part of
it there please.

[snip more comments that are totally out of context]

> >6)  Logging into the CVS server so you are authenticated and 
> can update files.
> 
> Assume I know nothing. Break it down into steps, do each 
> step, and explain what
> you're doing.

Yes, the docs with regard to CVS are, uhm, not good.  We can do better,
certainly.  I've already volunteered for one thing this email, not sure that
it would be good to volunteer for another.  Any takers?

> >7)  The $ is the shell prompt.  I guess I could use 
> [markk@wayga ~]$, but $
> is a bit simpler.  This is getting maybe to my biggest issue 
> with this.  We
> have to assume that LDP authors know *something* about Linux, 
> or else they
> wouldn't be writing.
> 
> You use different prompts in different examples. Be 
> consistent. Use the same prompt
> everywhere. Somewhere in your doc, explain what you are 
> doing. Books do this
> consistently, and usually use a different font for what the 
> computer types and what
> you type. They also explain their conventions up front.

I'd like to see us adopt some more formal conventions, and have them better
stated.  We could even provide a short section that people could just block
include into their HOWTOs that shows the general conventions.  For a good
online, current, DocBook example of that, check out the GNOME Documentation
Project's Guide to writing software documentation.  It's someplace on
http://www.gnome.org/GDP/  I haven't looked since the re-design, so I can't
say where it is.

> >8)  Serek (the CVS admin) asked that I include it.
> 
> He may have asked that you include it, but your duty is to 
> the reader. If you
> include it, you should explain it.

Assuming this is more about the CVS instructions, yeah, they need work.

> >9)  In case you don't have an account, or forget your 
> password, or have
> a guest user who likes CVS, I don't know.
> 
> Think about a prospective HOWTO author. Why would he/she want 
> anonymous access?

EASY.  CVS is the way to get the most current version of the documents by
some authors, they may want to tell their readers how to find the latest
version.  I could come up with more, but that's the most compelling one
offhand.  BTW Mark, I think it's Kosher to commit your HOWTO and it will get
processed and put on the LinuxDoc.org site.  

[snip]  Must have context.  Tired of me saying that yet?

> Last, I thought I'd repeat some discussion group messages and 
> remark on their
> relevance to the HOWTO-HOWTO
> 
> >I've read that the LDP uses a custom stylsheet for DocBook that
> generates a
> Table of Contents. Where can I get it?
> 
> This would be an appropriate thing for LDP to have under CVS 
> control and the HOWTO
> should have a pointer for getting it.

It's in CVS now.  If you're not on the CVS commits list, it's under
'builder/dsssl/ldp.dsl'.  

> >I've read the HOWTO-HOWTO and the section on style is very brief.
> Is there
> more guidance on how a HOWTO should be structured?
> 
> That's a valid question and one of the things I was trying to 
> address, particularly
> in the appendix on DocBook and in Step 4.

Was the question about Markup style, or about writing style?  They're
completely different, and both completely undefined.  

> >Does the LDP accept HOWTOs and mini-HOWTOs using the DocBook DTD?
> 
> A question that should be definitively answered.
> 
> Stein Gjoen <sgjoen@mail.nyx.net> says:
> >Style and structure are two different things but if structure
> is what you are loking for then I have a template under
> development
> here:
> 
> In Appendix A I was trying to give a usable template (by cut 
> and paste). Maybe we
> can get Stein to contribute his.

I think it would be nice to use Stein's template as THE template.  There are
now DocBook and Linuxdoc versions (as of earlier today I created a DocBook
version).  I disagree with some of the markup, and more of the content, but
I'll get to those soon.  

Anyway, that's enough out of me for a while, all the European guys should
get to read this in the morning (well in a few hours for them), so I'll have
something to do when I get up tomorrow.
	Greg


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