[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

RE: Proposed announcement etc, 2.nd revision

> -----Original Message-----
> From: Stein Gjoen [mailto:[email protected]]
> Sent: Monday, February 07, 2000 11:39 AM
> To: [email protected]
> Subject: Proposed announcement etc, 2.nd revision
> 
> I got some feedback on the proposed texts I posted 1.st february on
>  - announcement text
>  - intro.ldp manpage source
>  - intro.txt the above formatted
> 
> Additionally I am here submitting a proposal to the
> stub manpage for my own Multi Disk HOWTO, a manpage
> that I hope can make man -k <keyword> also find the
> HOWTO collection.
> 
> So, once again: please give me feedback!
> 
> (Straight off I just noticed the stub manpage didn't format well
> but I am not good at manpage authoring.)
> 
> I feel the announcement should be sent by the main
> contact address for the LDP, otherwise I am likely to
> receive a lot of incorrectly adressed email.
> 
> ==(Announcement)===
> 
> 
> After some restructuring of the Linux Documentation Project (LDP)
> we feel ready to serve the Linux community from the new home:
> 	http://www.linuxdoc.org/

To me this implies some major change has happened to the linuxdoc.org site
recently, something along the lines of the new site that the OSWG just put
up.  I don't think that this is really what we should be advertising,
although I don't have any better ideas.  

> 
> The LDP has collected and produced numerous documents such as
>  - guides
>  - HOWTOs and mini-HOWTOs
>  - FAQs
>  - man pages
> and more.
> 
> All in all the LDP endeavors to produce and provide a 
> one-stop source of
> information relating to the various aspects of Linux. There 
> is now also

I think I'd remove the word "also", it seems unnecessary here.

> a search engine on the front page to help you quickly and efficiently
> locate the documents you need. If you have a question, chances are you
> will find what you need here.
> 
> These documents are produced for you, the end users. That 
> means if there
> is anything in the documents you find unclear, ambiguous or incorrect
> you should not hesitate in contacting the author. While the 
> workload of
> the authors in general may be high and cannot be expected to 
> answer specific
> problems you may have on your machine, generally authors are 
> only happy to
> receive feedback on the documents.

Sounds good.

> 
> Likewise, if you feel you have something to contribute or you 
> wish to try
> your hands as an LDP author you are welcome to contact the 
> LDP coordinator
> with your inputs (see the HOWTO-HOWTO). Remember that new 
> documents are
> produced all the time so it is important to contact the LDP before you
> start writing in order to eliminate the possibility of duplicate work.

I haven't gotten a copy of the work that Jorge is working on, but if it's
ready for prime-time before this announcement goes out, perhaps it should be
included here as well.

> 
> Remember that you do not have to be on-line to read the 
> HOWTOs, in many
> cases these documents are installed with your Linux 
> distribution and can
> be found at
> 	file:///usr/doc/HOWTO	/usr/doc/HOWTO/
> 
> Regards,
>    Stein Gjoen
> 

[opaque man format yanked]

> ===(intro.txt)===
> 
> 
> LDP Introduction(ldp)                       LDP Introduction(ldp)
> 
> 
> NAME
>        LDP - Intro to the Linux Documentation Project, with help,
>        guides and documents
> 
> SYNOPSIS
>        The Linux Documentation Project, or LDP  for  short,  pro-
>        vides  free  documentation, guides, FAQs, HOWTOs and mini-
>        HOWTOs and man-pages to the Linux community.

I hate making comments like this, becuase I'm never confident that my
English is better than anybody else's, but I'd re-phrase the above as:
The Linux Documentation Project, or LDP for short, provides a variety of
free documentation, including Guides, FAQs, HOWTOs and mini-HOWTOs, and
man-pages for the Linux Community.  

Actually, looking at that, it's not any better, just a little different.
Maybe a couple more people can tell me why my phrasing is bad.

> 
> 
> AUTHORS
>        The various documents in the LDP archives  are  maintained
>        by  individual authors, and are listed in the beginning of
>        each HOWTO. If you have any questions or inputs to a docu-
>        ment we encourage you to contact the authors directly.
> 
> 
> WEB PAGES
>        The  LDP  now has its own dedicated web site as do many of
>        the various translations projects which  are  linked  from
>        the main LDP web site at http://www.linuxdoc.org/
> 
> 
> MAILING LISTS
>        LDP  has  a  number  of  mailing  lists, mostly of use for
>        authors:

This implies to me that the mailing lists are mostly for authors.  While I
don't write documentation specific to Linux, I'm on several of the lists.

> 
>        <[email protected]>
>               Announcements from the LDP project
> 
>        <[email protected]>
>               General discussion on the LDP project

Perhaps this section should contain the "request" addresses for these lists,
with brief subscription instructions (I.E. the command line issue to
subscribe).  I think that it should also tell how to get the info message
for these lists as a sort of "for more information on this list, send a
message with a body of info to [email protected] or
issue the command 'mail...' (sorry, I don't know how to use mail)".

> 
> 
> FILES
>        Most distributions include the HOWTOs and  mini-HOWTOs  in
>        the installation
>        /usr/doc/             (most documentation is here)
>        /usr/doc/HOWTO/       (HOWTO files)
>        /usr/doc/HOWTO/mini/  (mini-HOWTO files)
> 
> SEE ALSO
>        man(1)
> 
>        info pages as read with Emacs

Are we going to create info pages as well?

> 
> 
> 
> 
> LDP                      February 6, 2000                       1
> 
> 
> 
> 

[incomprehensible nroff whacked]

> 
> ===(disk.txt)===
> 
> Stub man page for the StubimanspageWforlthe Multi Disk HOWTO(ldp)
> 
> 
> NAME
>        Multi  Disk  HOWTO - Multi disk design, partitioning, for-
>        matting, tuning and maintenence
> 
> ABSTRACT
>        This document describes how best to use multiple disks and
>        partitions  for a Linux system. Although some of this text
>        is Linux specific the general approach outlined  here  can
>        be  applied to many other multi tasking operating systems.

Is this taken from the abstract in your HOWTO?  I tend to think that this
would be the easiest way to do things, if we're going to make a man page
available for all of the HOWTOs.

> 
> 
> FILES
>        Most distributions include the HOWTOs and  mini-HOWTOs  in
>        the installation
>        /dev/             (device files)
>        /etc/fstab        (mount list)
>        /etc/mdtab        (old style RAID table)
>        /etc/raidtab      (new style RAID table)
> 
> RELATED HOWTOS
>        Tips, Partition, Partition Rescue, Large-Disk, LILO, Soft-
>        ware-RAID, Upgrade
> 
> 
> SEE ALSO
>        fdisk(8), mount(8), mkfs(1), umount(8)
> 
> ==========

No where in this man page do you tell where to get the full text of your
Multi-disk HOWTO.  I think that this NEEDS to be part of the man page, or
there isn't any point in having the man page.  <flame> The idea is to get
the user some return on reading TFM, not to taunt them with the idea that
there's more information someplace, and not tell them where it is.  </flame>
Sorry Stein.  Thanks,
	Greg


--  
To UNSUBSCRIBE, email to [email protected]
with a subject of "unsubscribe". Trouble? Contact [email protected]