157 lines
6.3 KiB
HTML
157 lines
6.3 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
||
<!--X-Subject: Re: Style Guide (was Re: I'm a sucker) -->
|
||
<!--X-From-R13: Rnivq [reevyy <qpzreevyyNzvaqfcevat.pbz> -->
|
||
<!--X-Date: Fri, 6 Oct 2000 18:11:50 -0400 (EDT) -->
|
||
<!--X-Message-Id: 39DD1C60.569B658C@mindspring.com -->
|
||
<!--X-Content-Type: text/plain -->
|
||
<!--X-Reference: 39DD12BF.FE05CD21@rebel.net.au -->
|
||
<!--X-Head-End-->
|
||
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
||
<html>
|
||
<head>
|
||
<title>Re: Style Guide (was Re: I'm a sucker)</title>
|
||
<link rev="made" href="mailto:dcmerrill@mindspring.com">
|
||
</head>
|
||
<body>
|
||
<!--X-Body-Begin-->
|
||
<!--X-User-Header-->
|
||
<!--X-User-Header-End-->
|
||
<!--X-TopPNI-->
|
||
<hr>
|
||
[<a href="msg03947.html">Date Prev</a>][<a href="msg03949.html">Date Next</a>][<a href="msg03946.html">Thread Prev</a>][<a href="msg03962.html">Thread Next</a>][<a href="maillist.html#03948">Date Index</a>][<a href="threads.html#03948">Thread Index</a>]
|
||
<!--X-TopPNI-End-->
|
||
<!--X-MsgBody-->
|
||
<!--X-Subject-Header-Begin-->
|
||
<h1>Re: Style Guide (was Re: I'm a sucker)</h1>
|
||
<hr>
|
||
<!--X-Subject-Header-End-->
|
||
<!--X-Head-of-Message-->
|
||
<ul>
|
||
<li><em>To</em>: David Lloyd <<A HREF="mailto:lloy0076@rebel.net.au">lloy0076@rebel.net.au</A>></li>
|
||
<li><em>Subject</em>: Re: Style Guide (was Re: I'm a sucker)</li>
|
||
<li><em>From</em>: David Merrill <<A HREF="mailto:dcmerrill@mindspring.com">dcmerrill@mindspring.com</A>></li>
|
||
<li><em>Date</em>: Thu, 05 Oct 2000 20:27:12 -0400</li>
|
||
<li><em>Cc</em>: <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
||
<li><em>Old-return-path</em>: dcmerrill@mindspring.com</li>
|
||
<li><em>References</em>: <<a href="msg03946.html">39DD12BF.FE05CD21@rebel.net.au</a>></li>
|
||
<li><em>Resent-date</em>: Fri, 6 Oct 2000 18:11:50 -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>: <gWAwl.A.DnC.gxR35@murphy></li>
|
||
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-discuss-request@lists.debian.org">ldp-discuss-request@lists.debian.org</A></li>
|
||
<li><em>Sender</em>: dmerrill</li>
|
||
</ul>
|
||
<!--X-Head-of-Message-End-->
|
||
<!--X-Head-Body-Sep-Begin-->
|
||
<hr>
|
||
<!--X-Head-Body-Sep-End-->
|
||
<!--X-Body-of-Message-->
|
||
<pre>
|
||
David Lloyd wrote:
|
||
>
|
||
> I've unilaterally relabeled "I'm a Sucker" to Style Guide. It seems to
|
||
> fit in more with how some of the conversation is going. I've written a
|
||
> number of documents and documentation in my time. I guess one could say
|
||
> I have a slightly verbose (especially in the first draft), royal "we"
|
||
> style of writing. It fits in with my personality.
|
||
>
|
||
> Firstly, is there a "Style Guide HOWTO" or could this become a section
|
||
> of the "LDP Authoring Guide"?
|
||
>
|
||
> If there is not, and even if there is, I'm not sure that it would need
|
||
> to say too much. Nonetheless I think it should contain admonitions that:
|
||
>
|
||
> * one should avoid gender-specific language wherever possible
|
||
> - just to turn this one around a bit, why are crackers always
|
||
> referenced as "he"?
|
||
>
|
||
> * one should take into account that the audience is international, and
|
||
> that the document could be translated by someone not the author
|
||
> - covers things like don't show national prejudice
|
||
> - don't assume cultural backgrounds
|
||
> - try to avoid hard to translate idioms
|
||
|
||
These are all good ideas. When I do an update to the LAG, I'll implement
|
||
your suggestions. This could be some time, as I am very busy putting
|
||
together other things.
|
||
|
||
> * one shouldn't assume that all documentation is boring
|
||
> - without being overtly critical of any vendor, boring documentation is
|
||
> not read; despite what the management says, documentation that is
|
||
> interesting, sometime humurous and maybe even readable is of much more
|
||
> use than useless, wonderful, stilted management-liked documentation
|
||
>
|
||
> In the end the documentation is for the end user. It is not for the
|
||
> management of any vendor or specific user. Personally, I think the users
|
||
> should have a say; if there really were such a dislike of "so-called"
|
||
> non-professional documentation then those who don't like the current
|
||
> HOWTOs can go and sanitise them.
|
||
>
|
||
> I, for one, will still stay with the current HOWTOs. I cope with enough
|
||
> boring drudgery in my life without having to read boring documents...
|
||
|
||
I find the conversational style of many HOWTOs to be an essential part
|
||
of their charm. While one can find examples that are perhaps, ahem, a
|
||
bit *too* conversational, most are great. A balance between dry+boring
|
||
vs. conversational+wacky works well.
|
||
|
||
Regards,
|
||
|
||
--
|
||
David C. Merrill, Ph.D.
|
||
Linux Documentation Project
|
||
Collection Editor & Coordinator
|
||
|
||
|
||
--
|
||
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>
|
||
<ul><li><strong>Follow-Ups</strong>:
|
||
<ul>
|
||
<li><strong><a name="03962" href="msg03962.html">Re: Style Guide (was Re: I'm a sucker)</a></strong>
|
||
<ul><li><em>From:</em> Camille B<>gnis <camille@mandrakesoft.com></li></ul></li>
|
||
<li><strong><a name="03964" href="msg03964.html">Re: Style Guide (was Re: I'm a sucker)</a></strong>
|
||
<ul><li><em>From:</em> hjstein@bfr.co.il (Harvey J. Stein)</li></ul></li>
|
||
</ul></li></ul>
|
||
<!--X-Follow-Ups-End-->
|
||
<!--X-References-->
|
||
<ul><li><strong>References</strong>:
|
||
<ul>
|
||
<li><strong><a name="03946" href="msg03946.html">Style Guide (was Re: I'm a sucker)</a></strong>
|
||
<ul><li><em>From:</em> David Lloyd <lloy0076@rebel.net.au></li></ul></li>
|
||
</ul></li></ul>
|
||
<!--X-References-End-->
|
||
<!--X-BotPNI-->
|
||
<ul>
|
||
<li>Prev by Date:
|
||
<strong><a href="msg03947.html">Re: I'm a sucker</a></strong>
|
||
</li>
|
||
<li>Next by Date:
|
||
<strong><a href="msg03949.html">Re: LDP summit in Chapel Hill</a></strong>
|
||
</li>
|
||
<li>Previous by thread:
|
||
<strong><a href="msg03946.html">Style Guide (was Re: I'm a sucker)</a></strong>
|
||
</li>
|
||
<li>Next by thread:
|
||
<strong><a href="msg03962.html">Re: Style Guide (was Re: I'm a sucker)</a></strong>
|
||
</li>
|
||
<li>Index(es):
|
||
<ul>
|
||
<li><a href="maillist.html#03948"><strong>Date</strong></a></li>
|
||
<li><a href="threads.html#03948"><strong>Thread</strong></a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<!--X-BotPNI-End-->
|
||
<!--X-User-Footer-->
|
||
<!--X-User-Footer-End-->
|
||
</body>
|
||
</html>
|