Removing Roadblocks to LDP Authoring

On the staff list I posted a note that I've recruited a
couple of new
volunteers for LDP.  But then I checked on our site for what
to do to
become a volunteer and it said to read the Author Guide.  So
I started
to read this long and complicated book.  This  reconfirmed
my opinion
that we put too many roadblocks in the way of becoming an
author and
maintaining documentation.  I'm proposing that the process
be
drastically streamlined and that this change be made soon,
say within
a month.  You may not agree but I think that the
documentation that new
authors are required to read be shortened to a single page
or so.

That's right, I'm proposing to shorten the long and complex
LDP Author
Guide to a single page.  We can also revise the long
existing guide
too but reading it should be optional.

Now about markup.  LinuxDoc markup isn't much more difficult
than wiki
markup.  In a way it's simpler since one can readily
identify tags
since they are all enclosed in <>.  So I propose a
single-page (about
65 lines) Author Mini-HOWTO in LinuxDoc that will remain in
that
format.  That is, the HTML version will look just like
LinuxDoc
source, etc.  That way, when someone reads the HOWTO, they
also learn
the basics of LinuxDoc and see just how easy it is. 

I'll write a draft of this.  I've today already written a
one-page
reviewer howto for sampling reviewing where only samples of
the doc
are taken to save time.  I'll post these drafts to the staff
list
first and then to the this list.

I've started on such projects before but failed to follow
thru partly
due to people pointing out that what I proposed wasn't our
current
policy, etc.  Well, let's change our policy if it's needed. 
So what I
need to do now is to edit some stuff I've already written on
these
topics and get suggestions for change and improvement from
the mailing
lists.

And once we have new streamlined procedures and short info
for
authors, I hope to go back to recruiting from Linux User
Groups.

______________________
http://lists.tldp.org/

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


On Tue, 28 Nov 2006, David Lawyer wrote:

> Now about markup.  LinuxDoc markup isn't much more
difficult than wiki
> markup.  In a way it's simpler since one can readily
identify tags
> since they are all enclosed in <>.  So I propose
a single-page (about
> 65 lines) Author Mini-HOWTO in LinuxDoc that will
remain in that
> format.  That is, the HTML version will look just like
LinuxDoc
> source, etc.  That way, when someone reads the HOWTO,
they also learn
> the basics of LinuxDoc and see just how easy it is.

I think we should leave out everything about markup.  We do
state
somewhere (hidden behind the curtains) that an author can
send us any
format they want (although preferably it should be an Open
format) and
that we will convert it to what we want.  I think that is a
good idea and
it should be more clear to anyone who wants to submit a doc.
 And indeed
we should leave out the scary author guide and miscellaneous
collection of
other helpdocs for authors.

Tille.

- --
Machtelt Garrels                editorsen.tldp.org
Review Coordinator    	 	http://www.tldp.org/auth
ors/

My Penguin, my freedom.         http://tille.xalasys.com

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFFbWYHsIIUbMXbBA8RAoOvAJ0RiKmQpyNgTRo7/6te1W21WdIFwgCd
F0u5
5SlZy4uueqLbUK2dlSMRXtA=
=ZeDB
-----END PGP SIGNATURE-----


______________________
http://lists.tldp.org/

On Wed, Nov 29, 2006 at 10:50:43AM +0000, Machtelt Garrels
wrote:
> -----BEGIN PGP SIGNED MESSAGE-----
> Hash: SHA1
> 
> 
> On Tue, 28 Nov 2006, David Lawyer wrote:
> 
> > Now about markup.  LinuxDoc markup isn't much more
difficult than wiki
> > markup.  In a way it's simpler since one can
readily identify tags
> > since they are all enclosed in <>.  So I
propose a single-page (about
> > 65 lines) Author Mini-HOWTO in LinuxDoc that will
remain in that
> > format.  That is, the HTML version will look just
like LinuxDoc
> > source, etc.  That way, when someone reads the
HOWTO, they also learn
> > the basics of LinuxDoc and see just how easy it
is.
> 
> I think we should leave out everything about markup. 
We do state
> somewhere (hidden behind the curtains) that an author
can send us any
> format they want (although preferably it should be an
Open format) and
> that we will convert it to what we want.  I think that
is a good idea and
> it should be more clear to anyone who wants to submit a
doc.  And indeed
> we should leave out the scary author guide and
miscellaneous collection of
> other helpdocs for authors.

I think that the work of converting formats manually is a
lot of mostly
unproductive labor.  Isn't it hard to find volunteers to do
it?
What I would suggest is a list of volunteers to help with
markup that
authors could contact directly.  The docbook mailing list is
an
example of providing help and shouldn't we also have a
linuxdoc
mailing list too. 

When I can find time, I'm willing to attempt editing the
author guide
to remove the docbook bias, add the sampling review idea,
etc.  This
guide says that we prefer xml over sgml, but that statement
needs to
be qualified that it's only wrt docbook and not linuxdoc
which is sgml
and violates xml rules (which makes linuxdoc better IMO).

			David Lawyer

______________________
http://lists.tldp.org/

On Wed, Nov 29, 2006 at 07:31:59PM -0800, David Lawyer
wrote:
> On Wed, Nov 29, 2006 at 10:50:43AM +0000, Machtelt
Garrels wrote:
> > -----BEGIN PGP SIGNED MESSAGE-----
> > Hash: SHA1
> > 
> > 
> > On Tue, 28 Nov 2006, David Lawyer wrote:
> > 
> 
> What I would suggest is a list of volunteers to help
with markup that
> authors could contact directly.  The docbook mailing
list is an
> example of providing help and shouldn't we also have a
linuxdoc
> mailing list too. 
> 
> When I can find time, I'm willing to attempt editing
the author guide
> to remove the docbook bias, add the sampling review
idea, etc.  This
> guide says that we prefer xml over sgml, but that
statement needs to
> be qualified that it's only wrt docbook and not
linuxdoc which is sgml
> and violates xml rules (which makes linuxdoc better
IMO).
> 
> 			David Lawyer

David,

The first suggestion below is serious and has no smiley

Just drop linuxdoc. 

The above shows a _linuxdoc_ bias. If you're
going to have a format, docbook is about as well documented
and well 
used as you can find and has supportable toolchains. That's
the 
reason why, for example, debiandoc failed to catch on. I
know linuxdoc 
is your baby/hobby horse but move on.

Flat ASCII might be a better format, but is a little old


The real problem, however, is not documentation formats (go
back two or 
three years and we were starting to talk about wikis) it's
the fact that 
documentation ages and people can't be bothered to keep it
up to date.
That, and the fact that doing a Google search will normally
find a 
mailing list post somewhere faster than a relevant HOWTO.
Oh, and the 
fact that some HOWTOs are under the GFDL and therefore
"Debian 
not-free-enough-if-they-have-invariant-sections-but-OK-other
wise"

Of (say) 300 HOWTOs out there in English, how many are
current and owned 
by TLDP? How many are properly translated into other
languages?

I know I can get some howtos in French/German/Italian - but
how active 
is the documentation front there?

Do we need to be a universal resource?

Andy
> 
> ______________________
> http://lists.tldp.org/
> 


______________________
http://lists.tldp.org/

Andrew M.A. Cater a écrit :

> The first suggestion below is serious and has no smiley
> 
> Just drop linuxdoc. 

technically, the LDP lacks an universal editor. I mean a 
docbook editor suitable for anybody.

there where none two days ago, and I'm not aware of any now,

do you know one?

if there is still none, linuxdoc is much more writable with 
a basic editor than docbook (this is a nightmare)

> Of (say) 300 HOWTOs out there in English, how many are
current and owned 
> by TLDP? How many are properly translated into other
languages?

time ago, doc was lacking, but this is no more the case.

Google or/and a wiki adresses the needs of connected people 
(I know that, I'm sysop of http://fr.opensuse.org).

LDP try to adress a much bigger goal (having a source and 
many formats through backends), but the power users are 
already fitted, so volutaries go down

my own opinion is that we should have a wiki and write 
backends to go from there. but this idea was rejected 
several times ago, so I won't advocate it more now...

jdd


-- 
http://www.dodin.net

http://dodin.org/mediawiki/index.php/GPS_Lowrance_GO

______________________
http://lists.tldp.org/

-----BEGIN PGP SIGNED MESSAGE-----
Hash: SHA1


On Thu, 30 Nov 2006, Andrew M.A. Cater wrote:

> Of (say) 300 HOWTOs out there in English, how many are
current and owned
> by TLDP? How many are properly translated into other
languages?

About 130 are more or less current and actively maintained.
About 185 are abandoned.
About 80 addresses of authors have connection problems and
thus the status
is unknown.

Tille.


- --
Machtelt Garrels                editorsen.tldp.org
Review Coordinator    	 	http://www.tldp.org/auth
ors/

My Penguin, my freedom.         http://tille.xalasys.com

-----BEGIN PGP SIGNATURE-----
Version: GnuPG v1.4.1 (GNU/Linux)

iD8DBQFFbqgwsIIUbMXbBA8RAiknAJ0conkEpyTRbfkm5UJxWvoGszaiLACe
KGMo
hh+b5O7UWeKwL/RlUmBqJVI=
=/hQZ
-----END PGP SIGNATURE-----


______________________
http://lists.tldp.org/

> my own opinion is that we should have a wiki and write
backends to go 
> from there. but this idea was rejected several times
ago, so I won't 
> advocate it more now...

Oh, go ahead and advocate it!  I am!  My linuxwiki is doing
quite well. 
  I get numerous hits a day for the LDAP Authentication
document and 
that page shows up pretty close to the top of google
searches for many 
LDAP related searches.

   http://linuxwiki.riverworth.com/index.php/LDAP_Auth
entication

It's hard work to write good documentation.  It requires
time, planning, 
effort, re-reading, re-writing, and a bit of OCD.  And to
top it off, 
most people who know the stuff hate writing documentation. 
I know I do!

Language is another problem.  When somebody who is not a
native 
English-speaker (I use English just as an example; I'm sure
it applies 
to all languages), the text they write is often somewhat
difficult to 
understand by those that are native speakers.  It always
needs editing.

You can't avoid this.  My wife is French, speaking English
since early 
childhood.  She's fully bilingual by all standards.  Yet
there are still 
times when she misses some subtlety in English that
presumably is not 
there in French.

What was my point again?  Oh yes...  Documentation is hard! 
It requires 
the support of many people to get it right and _keep_ it
right.

                                           Brian
                                  ( bcwhiteprecidia.com )

------------------------------------------------------------
-------------------
  ... was no trading on the NYSE today; everybody was happy
with what 
they had.

______________________
http://lists.tldp.org/

On Thursday 30 November 2006 03:01 am, jdd wrote:
> my own opinion is that we should have a wiki and write
> backends to go from there. but this idea was rejected
> several times ago, so I won't advocate it more now...

+1 (sorry 

Randy Kramer

______________________
http://lists.tldp.org/

Brian White a écrit :
>> my own opinion is that we should have a wiki and
write backends to go 
>> from there. but this idea was rejected several
times ago, so I won't 
>> advocate it more now...
> 
> Oh, go ahead and advocate it!

go to http://lists.tldp.org/

and search "mediawiki jdd" to find all what I said
on the 
subject, and I wont repeat...

good luck 
jdd


-- 
http://www.dodin.net

http://dodin.org/mediawiki/index.php/GPS_Lowrance_GO

______________________
http://lists.tldp.org/

On Thu, Nov 30, 2006 at 09:01:49AM +0100, jdd wrote:
> Andrew M.A. Cater a écrit :
> 
> >The first suggestion below is serious and has no
smiley
> >
> >Just drop linuxdoc. 
> 
> technically, the LDP lacks an universal editor. I mean
a 
> docbook editor suitable for anybody.
> 
> there where none two days ago, and I'm not aware of any
now, 
> do you know one?
> 
Docbook Linux editor into Google gave me: 

Emacs, Vim, Vex, Conglomerate, Lyx - as a start. Emacs and
Lyx will do 
XML/SGML. A proprietary oxygenxml looks reasonable. Quanta
from KDE 
comes recommended.

> if there is still none, linuxdoc is much more writable
with 
> a basic editor than docbook (this is a nightmare)
> 
It's all markup of a text which you have to proof-read and
edit anyway.
Perhaps we need to look again at what we're doing.

Andy

> 


______________________
http://lists.tldp.org/