discuss: My rejected "replacement" for the Author Guide
Subject:
Re: My rejected "replacement" for the Author Guide
From:
"Martin A. Brown" ####@####.####
Date:
5 Feb 2016 18:02:02 +0000
Message-Id: <alpine.LSU.2.11.1602050940510.2025@znpeba.jbaqresebt.arg>
Hi there David (et alia),
>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 the top.
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.)
>It's on my website at www.lafn.org/~dave/linux/author-howto.html.
>It was rejected by Ferguson since it is in conflict with the Guide,
>which I referenced in the howto. I guess I was hoping that someone
>else would volunteer to revise the Guide but I wasn't following the
>list closely and didn't find the rejection email until years later.
>So what about using it as a basis and revising the Guide to conform
>with it.
I support the notion, however, I'd turn it around a bit and rather
incorporate your brief presentation into the LDP Author Guide.
Here's what I see and why I would make that choice. As an
organization, we have two little problems that could be addressed
by solving the problem this way:
#1: we need to publish consistent information about process and
expectations: TLDP still has (slightly) conflicting
information in several places [see earlier emails in 2016 on
this list].
#2: we need a shorter introduction to being an LDP author; your
document does that nicely
Now, where would we incorporate it? I suggest the LDP Author Guide,
specifically in the chapter/chunk which gives an overview of the LDP
process. If we get this right, it is really all an author needs to
know about interacting with us and what s/he can expect:
http://www.tldp.org/LDP/LDP-Author-Guide/html/process.html
I propose a two step incorporation and resolution of these two
texts:
#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.
I'd think that this would address the question of those who wish to
for a terse (essentially one-page) summary or overview of getting
their work accepted into the collection and making available all of
the support tools and recommendations that we have labored over the
years to add to the LDP Author Guide.
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?
>New acceptable formats I think should be plain text (except for
>guides) and html. I think that there is no strong need for any doc
>to be in all the formats we have been publishing in.
Again, I have no objection to supporting alternate formats.
As of today, I'm able to automatically produce outputs for all 501
of our Linuxdoc, DocBook SGML and DocBook XML sources. I have done
some of the output tree cleanup preparation.
I would like to improve the modularity of my automation scripts so
that we can support alternate input formats.
>Also see my linux page at www.lafn.org/~dave/linux/ I've got a
>proposal for using a sampling review there. I think that it's more
>efficient if just one person who understands the topic just does
>one sampling review.
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 two review process was created by LDP since some people in LDP
>didn't know the technical aspects very well.
I see. I did not know that. I guess that's something for our
review coordinator to think about!
Good suggestions and thank you,
-Martin
--
Martin A. Brown
http://linux-ip.net/
