discuss: Thread: Proposed modification of Manifesto. Do we agree?

This is a proposal to modify only the first section of the LDP
Manifesto (the Overview section).  But it's the most important part
since it describes our goals and how we are organized.  This draft is
not significantly modifying any basic policies or purposes, but it's
mainly making the manifesto conform to the current status of LDP.
However, it gives more emphasis to distribution of docs. via the
Internet which was not well established when the original Manifesto
was written in 1993.  It also makes it clear that LDP does not
normally document various Linux applications and utilities which come
with their own documentation.

If you would like to look at the earliest LDP Manifesto that I can
find on the Internet (from early 1993), go to
http://www.ibiblio.org/pub/linux/docs/ldpResearch/ldp-mails-public/ldp-1993-190

On Wed, Oct 05, 2005 at 03:47:41PM -0700, David Lawyer wrote:
[snip]
> Last night I looked at what I had drafted in 2001 for the "Overview"
> part of the Manifesto.  I then edited it a little to reflect the
> current situation.  My former draft stated that most major
> distributions distribute LDP documents.  This may no longer be true
> so I deleted it.  Also, I deleted the part about our documents being
> printed in books.  It's true that a few of our docs are also printed
> as books but I haven't seen any books recently that contain
> collections of HOWTOs, etc.
> 

From my previous draft, I've changed one sentence per suggestion from
Stein Gjoen and also made a few other minor changes.  What do people
think of it now?  I've retained LDP since there is some support for
continuing to use this name (but I don't know if there's consensus on
this).  The 2001 draft classified the integration of Linux
documentation an additional goal (and not the primary goal) although a
broad interpretation of the primary goal would include such
integration.  It's something that LDP hasn't yet done although a start
was made at one time.
--------------------------------------------------------------------------
		Draft of revised Overview section of "The Linux
		Documentation Project (LDP) Manifesto" by David S.
		Lawyer, 2001, with minor changes Oct. 2005

1. OVERVIEW
OLD   The Linux Documentation Project is working on developing free, high
OLD   quality documentation for the GNU/Linux operating system. The overall
OLD   goal of the LDP is to collaborate in all of the issues of Linux
OLD   documentation. This includes the creation of "HOWTOs" and "Guides". We
OLD   hope to establish a system of documentation for Linux that will be
OLD   easy to use and search. This includes the integration of the manual
OLD   pages, info docs, HOWTOs, and other documents.

The goal of the Linux Documentation Project (LDP) is to create and
distribute the canonical set of free, high quality GNU/Linux
documentation.  While GNU/Linux distributions, desktops, applications
and utilities may come with their own documentation, LDP documentation
fills in the numerous gaps.
 
The hundreds of existing LDP documents, such as HOWTOs and Guides,
present both overviews and details of: the GNU/Linux Operating System,
System Administration, Hardware, Networks, Servers, GUIs, Programming,
Language Support, etc.  Not every important topic is currently covered
so LDP is seeking new authors to fill in the gaps.

{Deleted from my previous draft: In spite of the large number of
documents, much more remains to be done and some areas are not
adequately covered.}

OLD   LDP's goal is to create the canonical set of free Linux documentation.
OLD   While online (and downloadable) documentation can be frequently
OLD   updated in order to stay on top of the many changes in the Linux
OLD   world, we also like to see the same docs included on CDs and printed
OLD   in books. If you are interested in publishing any of the LDP works,
OLD   see the section "[7]Publishing LDP Documents", below.

An additional goal is to collaborate on all of the issues of GNU/Linux
documentation. We hope to establish a system of documentation that is
easy to use and search. This includes the integration of manual pages,
info documents, HOWTOs, etc.

We freely distribute our documents via the Internet.  Some major
distributions of Linux include them on CDs.  If you are interested in
print publishing any of the LDP works, see the section "Publishing LDP
Documents" below.
  
{no change in last paragraph}
OLD   The LDP is essentially a loose team of [8]volunteers with minimal
OLD   central organization. Anyone who would like to help is welcome to join
OLD   in this effort. We feel that working together informally and
OLD   discussing projects on our mailing lists is the best way to go. When
OLD   we disagree on things, we try to reason with each other until we reach
OLD   an informed consensus.
   
The LDP is essentially a loose team of volunteers with a minimal
central organization. Anyone who would like to help is welcome to join
in this effort.  We feel that working together informally and
discussing projects on our mailing lists is the best way to go.  When
we disagree on things, we try to reason with each other until we reach
an informed consensus.

On Monday 31 October 2005 07:39, David Lawyer wrote:

| 		Draft of revised Overview section of "The Linux
| 		Documentation Project (LDP) Manifesto" by David S.
| 		Lawyer, 2001, with minor changes Oct. 2005
|

Hi David and list :-)

I have some remarks on this Draft ;
  i hope you find them helpfull.


| 1. OVERVIEW
| OLD   The Linux Documentation Project is working on developing free, high
| OLD   quality documentation for the GNU/Linux operating system. The overall
| OLD   goal of the LDP is to collaborate in all of the issues of Linux
| OLD   documentation. This includes the creation of "HOWTOs" and "Guides".
| We OLD   hope to establish a system of documentation for Linux that will be
| OLD   easy to use and search. This includes the integration of the manual
| OLD   pages, info docs, HOWTOs, and other documents.
|
| The goal of the Linux Documentation Project (LDP) is to create and
| distribute the canonical set of free, high quality GNU/Linux
| documentation.
What does "the canonical set" mean in this context ?

| While GNU/Linux distributions, desktops, applications 
| and utilities may come with their own documentation, LDP documentation
| fills in the numerous gaps.
Is "fills in the gaps" a goal or the current state ?

| The hundreds of existing LDP documents, such as HOWTOs and Guides,
| present both overviews and details of: the GNU/Linux Operating System,
| System Administration, Hardware, Networks, Servers, GUIs, Programming,
| Language Support, etc.  Not every important topic is currently covered
| so LDP is seeking new authors to fill in the gaps.
This sounds  as if LDP is nearing completion. Is that so ?

| {Deleted from my previous draft: In spite of the large number of
| documents, much more remains to be done and some areas are not
| adequately covered.}
|
| OLD   LDP's goal is to create the canonical set of free Linux
| documentation. OLD   While online (and downloadable) documentation can be
| frequently OLD   updated in order to stay on top of the many changes in the
| Linux OLD   world, we also like to see the same docs included on CDs and
| printed OLD   in books. If you are interested in publishing any of the LDP
| works, OLD   see the section "[7]Publishing LDP Documents", below.
|
| An additional goal is to collaborate on all of the issues of GNU/Linux
| documentation.
If this is a goal of the project,
  then with whom is the project to collaborate ?
Labouring doesnt sound like an ultimate goal to me.

| We hope to establish a system of documentation that is 
| easy to use and search.
[offtopic] if you already have a 'search all manpages' site, or program,
  could you point me to it please ?

| This includes the integration of manual pages, 
| info documents, HOWTOs, etc.
|
| We freely distribute our documents via the Internet.

| Some major distributions of Linux include them on CDs.
"Some" is an understatement.
  Debian is the biggest, and distributes LDP works.
But when i want to read a doc, and open the version on my Debian system,
  i first look at it's homepage, and download the latest version from there.
Maybe mentioning total downloadsize would be more impressive ?

| If you are interested in 
| print publishing any of the LDP works, see the section "Publishing LDP
| Documents" below.
|
| {no change in last paragraph}
| OLD   The LDP is essentially a loose team of [8]volunteers with minimal
| OLD   central organization. Anyone who would like to help is welcome to
| join OLD   in this effort. We feel that working together informally and OLD
|   discussing projects on our mailing lists is the best way to go. When OLD 
|  we disagree on things, we try to reason with each other until we reach OLD
|   an informed consensus.
|
| The LDP is essentially a loose team of volunteers with a minimal
| central organization. Anyone who would like to help is welcome to join
| in this effort.  We feel that working together informally and
| discussing projects on our mailing lists is the best way to go.  When
| we disagree on things, we try to reason with each other until we reach
| an informed consensus.

I think a relatively new challenge to documenting Linux distros
  is the great and rapidly increasing number of programs.
Is it also a goal of the project to make documentation accessible faster,
  more easily, more comprehensively ?

I am missing a description of the target group.
After all, even the best documentation is useless if nobody reads it.

Can the LDP be commercial ?
("Glossy Linux Tips WebMagazine", pay a dollar to have it mailed to you 
automatically ?)

I think the LDP is the best place to start looking for general linux 
documentation.


  have fun !

  Siward
  (home.wanadoo.nl/siward)

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


On Sun, 30 Oct 2005, David Lawyer wrote:

> This is a proposal to modify only the first section of the LDP
> Manifesto (the Overview section).  But it's the most important part
> since it describes our goals and how we are organized.  This draft is
> not significantly modifying any basic policies or purposes, but it's
> mainly making the manifesto conform to the current status of LDP.
> However, it gives more emphasis to distribution of docs. via the
> Internet which was not well established when the original Manifesto
> was written in 1993.  It also makes it clear that LDP does not
> normally document various Linux applications and utilities which come
> with their own documentation.

I agree with these changes.

Tille.

- --
Machtelt Garrels                ####@####.####
Review Coordinator    	 	http://www.tldp.org/authors/

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


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

iD8DBQFDewOCsIIUbMXbBA8RAtqRAKCMAJLPPZsQnSLm8I7qY7I49wSXUQCdHqdh
2n4thMJzvZWTjggYEY2pWZ8=
=TPAR
-----END PGP SIGNATURE-----

On Wed, Nov 02, 2005 at 12:20:19AM +0200, Siward de Groot wrote:
> On Monday 31 October 2005 07:39, David Lawyer wrote:
> 
> | 		Draft of revised Overview section of "The Linux
> | 		Documentation Project (LDP) Manifesto" by David S.
> | 		Lawyer, 2001, with minor changes Oct. 2005
> |
> 
> Hi David and list :-)
> 
> I have some remarks on this Draft  i hope you find them helpfull.
> 
> 
> | 1. OVERVIEW
> | OLD   The Linux Documentation Project is working on developing free, high
> | OLD   quality documentation for the GNU/Linux operating system. The overall
> | OLD   goal of the LDP is to collaborate in all of the issues of Linux
> | OLD   documentation. This includes the creation of "HOWTOs" and "Guides".
> | We OLD   hope to establish a system of documentation for Linux that will be
> | OLD   easy to use and search. This includes the integration of the manual
> | OLD   pages, info docs, HOWTOs, and other documents.
> |
> | The goal of the Linux Documentation Project (LDP) is to create and
> | distribute the canonical set of free, high quality GNU/Linux
> | documentation.
> What does "the canonical set" mean in this context ?
It was in the original and it seems to mean the major set of Linux
documentation.  It's a goal and we probably haven't reached that goal
yet.  In the dictionary canonical means official or recognized.
> 
> | While GNU/Linux distributions, desktops, applications 
> | and utilities may come with their own documentation, LDP documentation
> | fills in the numerous gaps.
> Is "fills in the gaps" a goal or the current state ?
It's both.  It currently fills in many gaps but there are still a lot
of gaps to fill.
> 
> | The hundreds of existing LDP documents, such as HOWTOs and Guides,
> | present both overviews and details of: the GNU/Linux Operating System,
> | System Administration, Hardware, Networks, Servers, GUIs, Programming,
> | Language Support, etc.  Not every important topic is currently covered
> | so LDP is seeking new authors to fill in the gaps.
> This sounds  as if LDP is nearing completion. Is that so ?
No.  I supported being more frank as you can see below.  But Stein
Gjoen thought it was too negative.  What do others think about this?
> 
> | {Deleted from my previous draft: In spite of the large number of
> | documents, much more remains to be done and some areas are not
> | adequately covered.}
> |
> | OLD  LDP's goal is to create the canonical set of free Linux 
> | OLD documentation.  While online (and downloadable) documentation
> | OLD can be | frequently updated in order to stay on top of the
> | OLD many changes in the Linux world, we also like to see the
> | OLD same docs included on CDs and printed in books. If you are
> | OLD interested in publishing any of the LDP works, see the section
> | OLD "[7]Publishing LDP Documents", below.
> |
> | An additional goal is to collaborate on all of the issues of GNU/Linux
> | documentation.
> If this is a goal of the project, then with whom is the project to
> collaborate ?   Labouring doesnt sound like an ultimate goal to me.

It doesn't say but for example, we would need to collaborate with FSF
,the Linux Manual Pages Project, and FHS (File Hierarchy Standard).
And also possibly with the LSB (Linux Standard Base), FSG (Free
Standard Group), and Debian.  Prior to such collaboration, we need to
come up with a proposal on how to integrate documentation.

> 
> | We hope to establish a system of documentation that is 
> | easy to use and search.
> [offtopic] if you already have a 'search all manpages' site, or program,
>   could you point me to it please ?
You must mean search all Linux Documentation.  Google, etc. can do
this.
> 
> | This includes the integration of manual pages, 
> | info documents, HOWTOs, etc.
> |
> | We freely distribute our documents via the Internet.
> 
> | Some major distributions of Linux include them on CDs.

> "Some" is an understatement.  Debian is the biggest, and distributes
> LDP works.  But when i want to read a doc, and open the version on
> my Debian system, i first look at it's homepage, and download the
> latest version from there.  Maybe mentioning total downloadsize
> would be more impressive ?
Better yet, convince Debian to use the latest docs and not freeze them
like it does for software.
> 
> | If you are interested in 
> | print publishing any of the LDP works, see the section "Publishing LDP
> | Documents" below.
> |
> | {no change in last paragraph}
> | OLD   The LDP is essentially a loose team of [8]volunteers with minimal
> | OLD   central organization. Anyone who would like to help is welcome to
> | join OLD   in this effort. We feel that working together informally and OLD
> |   discussing projects on our mailing lists is the best way to go. When OLD 
> |  we disagree on things, we try to reason with each other until we reach OLD
> |   an informed consensus.
> |
> | The LDP is essentially a loose team of volunteers with a minimal
> | central organization. Anyone who would like to help is welcome to join
> | in this effort.  We feel that working together informally and
> | discussing projects on our mailing lists is the best way to go.  When
> | we disagree on things, we try to reason with each other until we reach
> | an informed consensus.
> 
> I think a relatively new challenge to documenting Linux distros is
> the great and rapidly increasing number of programs.  Is it also a
> goal of the project to make documentation accessible faster, more
> easily, more comprehensively ?
 
Well, it says:
 We hope to establish a system of documentation that is easy to use and search.

> I am missing a description of the target group.  After all, even the
> best documentation is useless if nobody reads it.
The target group depends on the document and it may be that a doc has
parts that are more advanced than others and intended for different
target groups.

> Can the LDP be commercial ?
No.  We're dedicated to free documentation.
>("Glossy Linux Tips WebMagazine", pay a dollar to have it mailed to you automatically ?)

> I think the LDP is the best place to start looking for general linux 
> documentation.
> 
>   have fun !
> 
>   Siward
>   (home.wanadoo.nl/siward)
> 
> 
> ______________________
> http://lists.tldp.org/
> 
			David Lawyer