Writing introductory documentation; looking for feedback

[THOMAS EDWARD HART]

Hello, all!

I'm writing some introductory documentation for the Hurd.
It's aimed at three groups:

1. People who are complete end-users; I try to tell them the
basic idea of what the Hurd is, and then advise them to use 

something more stable (like Debian GNU/Linux) for now.
2. People who know how to program, but have little to no
practical knowledge of how to use any Free UNIX-like system (I 

advise introductory computer science labs, and I see many
such people.)
3. People are great hackers, and can use GNU/Linux like
nobody's business, but don't have a strong background in
operating 

systems, and likely believe that microkernels are not a good
thing (I know people like this too).

I want people in the latter two groups to be able to go over
my documentation, and then have the background to (mostly) 

understand the current introductory material (such as
_Towards a New Strategy of OS Design_ and _The Hurd Hacking
Guide_). I 

hope that, when completed, this documentation can be added
to the official GNU documentation at hurd.gnu.org.

I'm drawing from my own experiences here. I'm a comp sci
major, and I thought UNIX was a programming language in
first year, 

and didn't start learning to use GNU/Linux until after
second. I've been at it for about a year now. And like I
said before, 

many people who are learning to be programmers started using
computers after Win95 replaced DOS, and don't know how to use a 

command shell. So this is the sort of person for whom I'm
trying to write some good documentation.

I first suggested this to Wolfgang on IRC about a month ago,
and have been brainstorming, looking at other documentation,
and 

taking a look at TexInfo since then. The documentation is
far from complete, but I've written much of the introductory
page, 

and laid out the structure of the rest.

I would appreciate any feedback any of you can give me. I
would be especially interested in hearing what resources
helped you 

as you were first learning UNIX. What could help someone who
has never seen UNIX before learn what (s)he needs in order to 

use and help with the Hurd?

-- Tom Hart
hartte13@brandonu.ca

[ English ]

An Introduction to the GNU Hurd   A Course of Study   How to use the GNU System   How To Help Find Bugs in the GNU Hurd   Understanding the Design Advantages offered by the GNU Hurd   Writing Documentation for the GNU Hurd and the GNU System   Developing Software that Uses the Features of the GNU Hurd   Helping to Develop the GNU Hurd

An Introduction to the GNU Hurd To understand the GNU Hurd, a few things must be put in context: UNIX is an operating system developed in 1969 by Ken Thompson and Dennis Ritchie at AT&T Bell Laboratories; An operating system manages your computers hardware an allows other, more useful, programs to run; Other examples of operating systems are GNU/Linux, AtheOS, FreeBSD, Mac OS X, and Windows XP; Any one of the operating systems mentioned above can be substituted for any of the others, and can run a computer, but each has different strengths and limitations; The GNU Project was started by Richard Stallman in 1983 to develop a free UNIX-compatible operating system, called the GNU System; The GNU system uses a microkernel (this term will be explained later) as its core; No microkernel provides the functionality of the UNIX kernel; The Hurd is a set of servers (a type of program; again, this will be explained later) that, along with a microkernel and the GNU C Library (later...), provide the full functionality of the UNIX kernel; This design is more flexible than that of UNIX or Linux, and offers many advantages that we will explore later in this documentation. The Hurd is under active development; its most current release is version 0.2 (traditionally, software is released as version 1.0 when its creators feel that is it sufficiently bug-free for everyday use). Click here to see if the Hurd offers something for you. A Course of Study In order to use, understand, and contribute to the GNU Hurd, there are several topics with which you should become familiar. These topics can be sorted according to what you need to know to: use the GNU System; help find bugs in the GNU Hurd; understand the design advantages offered by the GNU Hurd; write documentation for the GNU Hurd and the GNU System; develop software that uses the features of the GNU Hurd; and help develop the GNU Hurd. Most of the introductory documentation for the Hurd; for example, the FAQ, the paper Towards a New Strategy of OS Design, and the Hurd Hacking Guide assume that the reader is already very familiar with UNIX-like operating systems, and with several important pieces of Free Software. These links will guide you through learning this material. How To Use the GNU System Eat the acronym soup: There are many acronyms and other terms that a user will encounter when using Free Sofware; a glossary is available at tuxedo.org. Explanations of other terms can usually be found by searching the web. Command shells: Although projects like GNOME and KDE are bringing convenient modern desktop environments to UNIX-like systems, the command line is still extremely important. This is especially true for systems using the Hurd, since much of the installation and initial configuration must be done using the command line. Most operating systems include text-based command shell, although some systems de-emphasize them. If you search your system's help utility for "text-based command shell", it will likely tell you how to start and use your system's command shell. Much of what you learn on one command shell can be transferred to others. NEED A LINK TO A COMMAND-LINE HOWTO. Learn some basics about computer hardware: Some knowledge of your computer's hardware is necessary in order to install and run any free operating system. You should know, for example, whether your mouse is serial, PS/2, or USB, whether your hard drive(s) is(are) IDE or SCSI, and other such information. AGAIN, NEED A LINK. Install and learn to use a free UNIX-like operating system: We recommend you use Debian GNU/Linux. Debian is a distribution of GNU/Linux; that is, they package and configure software for GNU/Linux, make sure it works together, and distribute it. We recommend Debian because it is completely free (see the Debian Social Contract), and because the Debian is currently the only distributor of GNU/Hurd systems (see Debian GNU/Hurd). Some people, however, find Debian's learning curve too steep. If you are such a person, you may want to start with a distribution geared more towards beginners; Mandrake does a good job of this without making the system unusable for hackers. Buying a boxed set from a commercial distribution has the added benefit that you will get printed documentation that will help you as you begin your learning. Become familiar with sources of information on the Internet: Many Internet sites contain extensive documentation; some good ones include: GNU Manuals Online for GNU software; The Linux Documentation Project , which offers many HOWTOs and tutorials; and LinuxNewbie.org , which offers "newbieized help files" aimed at beginers. Learn the important command-line tools: These include less, grep, and find. OTHER IMPORTANT ONES??? How To Help Find Bugs in the GNU Hurd Bug reports for the Hurd should go to the bug-hurd mailing list. When submitting a bug report, keep in mind that the the bug can only be fixed if the Hurd developers are able to reproduce your error. Hence, you should give them enogh information to be able to do so. This includes: Your computer's hardware; What you were doing when the error occurred; Very importantly, the exact error message outputted by the offernding program, if one exists. INCLUDE LINK TO ERIC S. RAYMOND'S PIECE ON BUG REPORTING. TODO: Something about how to find bugs, and what bug reporting tools are available. Much of this stuff I still have to learn myself, so any suggestions would be appreciated. Understanding the Design Advantages offered by the GNU Hurd This section will provide a link to a short introduction to operating system theory aimed at people with a strong technical background, but who lack a good grounding in operating system theory. It'll try to clear up some of the anti-microkernel FUD, and help scuttle the sort of anti-Hurd comments I saw on Slashdot when the most recent version of GNU Mach was released. This, and any other documentation I write to which this page will provide a link, will be generated with TexInfo. Also provide a link to Debian's documentation on translators. After reading this section, the reader should have the background to read and understand Towards a New Strategy of OS Design, and Marcus' talk. Writing Documentation for the GNU Hurd and the GNU System TODO: links to GNU documentation standards, TexInfo manuals, WC3 recommendations, intoductory HTML tutorial or two. Developing Software that Uses the Features of the GNU Hurd Talk about GCC and GDB, provide links to their documentation, etc. Also provide a link to the GNU C book on Savannah, and a link to it as HTML (since many readers will be reading this from a non-GNU system, so we can't rely on them having TexInfo. Also recommend K&R to the reader. Helping to Develop the GNU Hurd At this point, what I write will start to bleed into Wolfgang's The Hurd Hacking Guide.

---

[ English ]

---

Go to GNU's home page.

Copyright (C) 2002 Thomas Edward Hart

Verbatim copying and distribution of this entire article is permitted in any medium, provided this notice is preserved.

Updated: $Date: 2002/07/25 03:07:20 $ $Author: tomhart $

---

baby-hurd.jpg
Description: JPEG image