281 lines
11 KiB
HTML
281 lines
11 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: Authorship -->
|
|
<!--X-From-R13: Unel Berpxfubg <tneeryyNvaernpu.pbz> -->
|
|
<!--X-Date: Tue, 30 May 2000 19:47:05 -0400 (EDT) -->
|
|
<!--X-Message-Id: 393450A8.B31B99FE@inreach.com -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--X-Reference: 20000527130824.A26622@titan.oit.unc.edu -->
|
|
<!--X-Reference: 39302F05.169A01E9@inreach.com -->
|
|
<!--X-Reference: 39308F68.1203C19C@cgipc.com -->
|
|
<!--X-Reference: 3932F590.94942D57@inreach.com -->
|
|
<!--X-Reference: 3933CA7B.9EA19C1A@cgipc.com -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Authorship</title>
|
|
<link rev="made" href="mailto:garrell@inreach.com">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg02570.html">Date Prev</a>][<a href="msg02572.html">Date Next</a>][<a href="msg02535.html">Thread Prev</a>][<a href="msg02533.html">Thread Next</a>][<a href="maillist.html#02571">Date Index</a>][<a href="threads.html#02571">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>Authorship</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: LDP <<A HREF="mailto:ldp-discuss@lists.linuxdoc.org">ldp-discuss@lists.linuxdoc.org</A>></li>
|
|
<li><em>Subject</em>: Authorship</li>
|
|
<li><em>From</em>: Gary Preckshot <<A HREF="mailto:garrell@inreach.com">garrell@inreach.com</A>></li>
|
|
<li><em>Date</em>: Tue, 30 May 2000 16:37:12 -0700</li>
|
|
<li><em>References</em>: <<a href="msg02520.html">20000527130824.A26622@titan.oit.unc.edu</a>> <<a href="msg02523.html">39302F05.169A01E9@inreach.com</a>> <<a href="msg02529.html">39308F68.1203C19C@cgipc.com</a>> <3932F590.94942D57@inreach.com> <3933CA7B.9EA19C1A@cgipc.com></li>
|
|
<li><em>Resent-date</em>: Tue, 30 May 2000 19:47:05 -0400 (EDT)</li>
|
|
<li><em>Resent-from</em>: <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
|
<li><em>Resent-message-id</em>: <DyCDw.A.13B.zLFN5@murphy></li>
|
|
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-discuss-request@lists.debian.org">ldp-discuss-request@lists.debian.org</A></li>
|
|
</ul>
|
|
<!--X-Head-of-Message-End-->
|
|
<!--X-Head-Body-Sep-Begin-->
|
|
<hr>
|
|
<!--X-Head-Body-Sep-End-->
|
|
<!--X-Body-of-Message-->
|
|
<pre>
|
|
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
|
|
|
|
</pre>
|
|
|
|
<!--X-Body-of-Message-End-->
|
|
<!--X-MsgBody-End-->
|
|
<!--X-Follow-Ups-->
|
|
<hr>
|
|
<!--X-Follow-Ups-End-->
|
|
<!--X-References-->
|
|
<ul><li><strong>References</strong>:
|
|
<ul>
|
|
<li><strong><a name="02520" href="msg02520.html">geekness</a></strong>
|
|
<ul><li><em>From:</em> Guylhem Aznar <guylhem@metalab.unc.edu></li></ul></li>
|
|
<li><strong><a name="02523" href="msg02523.html">Re: geekness</a></strong>
|
|
<ul><li><em>From:</em> Gary Preckshot <garrell@inreach.com></li></ul></li>
|
|
<li><strong><a name="02529" href="msg02529.html">Re: geekness</a></strong>
|
|
<ul><li><em>From:</em> Mark Komarinski <markk@cgipc.com></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg02570.html">Re: search capability (was: Re: [OT] OpenSource Documentation Fund)</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg02572.html">Re: HOWTOs in DocBook SGML?</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg02535.html">Re: geekness</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg02533.html">HOWTO-HOWTO, was Re: geekness</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#02571"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#02571"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|