discuss: My rejected "replacement" for the Author Guide
Subject:
Re: My rejected "replacement" for the Author Guide
From:
"Martin A. Brown" ####@####.####
Date:
9 Feb 2016 15:58:50 +0000
Message-Id: <alpine.LSU.2.11.1602090744560.2025@znpeba.jbaqresebt.arg>
Hello and good morning,
>> >Almost 10 years ago I thought that our Author Guide was so long and
>> >complex that it would scare away potential authors so I wrote a
>> >howto on this topic.
>>
>> In principle, I agree. When I first contributed, I also found the
>> LDP Author Guide a bit intimidating. (Later, I found the detail
>> immensely helpful.)
>
>When I came to LDP in 1998 there was no Author Guide. But there
>was a 3-page (printed) learn-by-examples for Linuxdoc and one just
>emailed in submissions. A new leader, Lars Wirzenius, in early
>1999 automated submissions and it worked (I used it), but he
>resigned due to not wanting to tolerate insults and then no one
>continued to implement his (beta) automated submission system.
>Under Lars' system, you just emailed to a submit address and sent
>your password in the clear. So LDP had simple automatic submission
>17 years ago.
Ah, interesting. Neat.
That reminds me of the first-generation of tools for whois domain
and Internet number resource management. There was an email gateway
that would handle change requests. In the late 1990s, this fell by
the wayside because of ease of abuse. [Some used cryptographic
tools to secure the content and provide authorization, but
eventually, web applications and interfaces riding on HTTP
supplanted this.]
>> #1: Knit your much shorter author-howto text into the existing LDP
>> Author Guide.
>>
>> #2: Rename the section so that it's obviously something like
>> "Overview" or "Quickstart" or "How do I contribute?"; once it's
>> written, I'd think we would link to that canonical location from
>> TLDP's web site.
>>
>> If you agree, David, I'd bet that Mark Komarinski or I would undertake
>> the incorporation of your text. How do you feel about that?
>
>I still think it would be better as a standalone, but OK, put it
>into the Guide. I would like to see the Authors Guide changed so
>that it doesn't show how to deal with docbook.
I see your point here about separating the process/policy content in
the LDP Author Guide from the technical matters, which will differ
depending on format and tooling.
I'd hate to remove the good DocBook information from the LDP Author
Guide, but if we are going to accept multiple formats, it would be
good to examine the LDP Author Guide to see where we could
de-emphasize DocBook, while retaining the valuable information for
those who do choose DocBook.
Mark: Any objections to some adjustment of LDP Author Guide along
those lines? I'd be happy to volunteer to read, suggest and
possibly provide patches, if you would like.
>How to use docbook, linuxdoc, or wikis (such as the wiki used for
>Wikipedia) belongs in other howtos.
>If it's to be put into the Guide, I could add paragraph tags to
>blank lines, but in the past I couldn't get docbook to work on this
>old PC (which I'm still using).
OK. It's like the old comfortable pair of socks!
>> I read through that. That seems OK to me. I think, as a volunteer
>> organization, we can use different strategies for undertaking a review.
>>
>> Ultimately, any review, even a sampling review, is likely only to drive
>> value into the document by addressing technical oversights, errors and
>> bad advice.
>
>The purpose of a sampling review is not to provide the author with
>a list of errors since most of the errors will be missed due to
>sampling. Its purpose is mainly to determine if tLDP should accept
>the document or if it needs more work before accepting it. We have
>to be selective since when we weren't, we wound up with documents
>that had negative value due to errors (including intentional ones).
Right. Absolutely understood.
-Martin
--
Martin A. Brown
http://linux-ip.net/
