Authorship

[Gary Preckshot <garrell@inreach.com>]

Mark Komarinski wrote:

>First, thanks.

You're welcome.

>It does seem a bit easier to read, though you did
take out some of the concepts that I really wanted new authors
to read.

I'm trying to move that into appendices with references to the appendix in the body.
<Link> works fairly well. The idea is to give a concise description in the body
without interrupting the reader's train of thought. The link lets him/her follow up
whenever convenient. I may have remove something you think is important, and we
should get it back in, but being mindful of how immediately useful it will be to
prospective authors. As a parenthetical remark, Step 4 is probably too long and
should have its own appendix. We should just hit the high points in the body.

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.

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

>5)  It's irrelevant since those commands don't work with DocBook.

So why didn't you say so, and why is it taking up space?

>6)  See 3.

That certainly seems relevant.

7)  Probably right, but I do give a bit of a hint of what the idea is.

Consider this a data point. I read it and didn't have even a glimmer of an idea what
it meant. The more so because there were no screen shots of LyX in action.

>8)  Do you mean like a sourceforge kind of idea?

I don't know what sourceforge is, but in a HOWTO, if you tell people to do
something, there should either be a lucid explanation of how to do it, or a pointer
to a place where there's a mechanism to do it. Considering how important it is for
LDP to get comments, this is a function LDP should provide.

>"FAQs about the LDP"

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

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

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

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

>5)  Not sure that's necessary, but okay.

Don't tell our readers to do something and then not tell them how to do it. It's
extremely geeky to assume that everybody is set up the way you are. What works for
you probably won't work for them.

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

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

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

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

>10) That's really outside the scope of this, I think.  Too much information
(verbosity) will only confuse authors.

It confused me just being mentioned off-hand. Does LDP use this or other entries
that CVS can put into a document. Verbosity comes in several flavors. One is saying
something out of the blue with no apparent motivation.

Please take these comments as data. One of the things that can be maddening about
something like a HOWTO is incompleteness. The opposite extreme is too much
irrelevancy. We can counter both by organization. Put the lengthy explanations in
appendices and put yourself in the shoes of a newbie. They aren't going to know how
to do a lot of things, and consistency goes a long way toward not confusing them
with irrelevancies.

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.

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

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

Gary


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