RFQ on Linux Documentation
andy wessels
In an effort to consolidate the volume of documentation that is appearing, it seems proper to adopt a 'standard' for the documentation. A proposed method would
to have a first section to represent the official FAQ of what linux is, how to
obtain, hardware considerations, and a list of other supporting documents.
This could be followed by the first 'chapter'--an historical perspective of linux.
Second chapter could be installation notes.
Third chapter could be media use.
floppy drive linux use
hard drive (mfm/rll) use
SCSI drive use
Fourth chapter could be setting up the boot manager.
Fifth chapter could be the use of the compilers. This would entail things like
shared libraries vs. static, where to put the files, problems, etc.
Sixth chapter could be where to put the rest of the binaries. eg.-the linux
filesystem standard
Seventh chapter could be mouse support and how to set up a mouse.
Eighth and ninth chapter could be for X11 support--one for setting up X11, and
one for the basic software questions.
Tenth chapter could be for how-to-use-the-binaries-in-the-install-disk.
eleventh chapter devoted to UUCP issues.
(other chapters as needed)
The overall goal is to have a definative source for the FAQ of each part of linux. This could be a 'huge' FAQ, but divided up into seperate 'chapters' so that a person can first find what is needed, and second, only needs to look at the proper 'chapter'. At this stage, I _do_not_ want a war about this chapter
belongs before that chapter. I am interested in the concept at this stage. As
linux gains momentum with non-hackers, and as the kernel services expand, the overall success or failure of good documentation can make or break the project. Hackers will tend to migrate to this environment, but for the unix newcomer without much knowledge of sys. admin, there will need to be some sort of dicumentation. This scheme of different chapters will lend itself well to the
very distributed nature of linux.
As it stands right now, there is documentation available. However, it is sometimes hard to put a handle on where the answer to the question is. This is an attempt to help clarify what has been written, what needs to be written, and what will be written in the future.
comments, questions, concerns...
Cory West
a...@thor.cc.nd.edu (andy wessels) writes:
> I do not really want to start another thread, but the documentation seems
> to be getting out of hand....
>
[Idea on chapters deleted]
I like this idea a lot. I can take a chapter (or help with a
chapter). It might/would/could be a good idea to consolidate all
documentation and the chapter style lends itself to texinfo documents.
This way, the Linux Info Structure could be browsed from Emacs,
printed via tex, or simply read in text format (after being properly
translated).
Who are the current documentation people? Any more ideas?
Cory West
Darren Senn
>In article <1992Jul6.1...@news.nd.edu>
>a...@thor.cc.nd.edu (andy wessels) writes:
>> I do not really want to start another thread, but the documentation seems
>> to be getting out of hand....
I tried to respond to this earlier, but my news reader/poster was busted. :(
This kind of Magnum Opus of documentation is being worked on by a subgroup
of the man project. They're calling their work the "Hitchhiker's Guide",
and they've been working for at least a month. You should talk to them
to see what they've already done.
--
Darren Senn Phone: (408) 479-1521
sin...@scintilla.capitola.ca.us Snail: 1785 Halterman #1
Wasurenaide -- doko e itte mo soko ni anata wa iru yo. Santa Cruz, Ca 95062
Ben Cox
join the linu...@stolaf.edu mailing list.
Send mail to linux-ma...@stolaf.edu to join.
--
Ben Cox
th...@uiuc.edu
James Henrickson
I intended to respond to Andy's post, but the school's hard drive was full
again. :-(
The documentation effort will be greatly simplified by using the FAQs as
a starting point. Reorganize the FAQs, reword them, coordinate with the
FAQ people, and coordinate with the people involved in the various aspects
of Linux (Linux itself, GCC, X11, etc) to make sure the information is
correct. Reword the installation instructions and add steps as necessary.
The result should be much better documentation without a lot of effort.
I'm sure that Linus, HJ, obz, etc. would be willing to work with a
designated documentor, as it should reduce the amount of mail they have
to answer from everyone else and therefore giving them more time to work
on their projects.
Just a suggestion. :-)
--
Jim H.
*
* James L. Henrickson uj...@sunyit.edu
* "Yet another Jim in the Linux world." :-)