I've completed a first through on everything in the introduction. I
[fspm_howto] / FreeSoftwareProjectManagementHOWTO.sgml
1 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook V3.1//EN">
2
3 <article>
4
5 <!-- Header -->
6
7  <artheader>
8   <title>Free Software Development HOWTO</title>
9
10   <author>
11      <firstname>Benjamin</firstname>
12      <othername>Mako</othername>
13      <surnamen>Hill</surname>
14      <affiliation>
15         <address>
16            <email>mako@debian.org</email>
17
18         </address>
19      </affiliation>
20   </author>
21
22    <revhistory>
23       <revision>
24          <revnumber>v0.01</revnumber>
25          <date>1 January 2001</date>
26          <authorinitials>bch</authorinitials>
27           <revremark>
28           Initial Release
29          </revremark>
30       </revision>
31    </revhistory>
32
33   <abstract>
34     <indexterm>
35       <primary>fswd</primary>
36     </indexterm>
37
38     <para>
39      This HOWTO is designed for people with experience in programming
40      and some skills in managing a software project but who are new to
41      the world of Free Software. This document is meant to act as a
42      guide to the non-technical aspects of programming and was written
43      to act as a crash course in the people skills that aren't taught
44      to commercial coders but that can make or break a free software
45      project.
46     </para>
47   </abstract>
48
49  </artheader>
50
51 <!-- Section1: intro -->
52
53  <sect1 id="intro">
54    <title>Introduction</title>
55
56    <indexterm>
57     <primary>fswd!introduction</primary>
58    </indexterm>
59
60   <para>
61    For various reasons, this realease has been codenamed the
62    <emphasis>homade yogurt</emphasis> release.
63   </para>
64
65   <para>
66    New code names will appear as per industry standard
67    guidelines to emphasize the state-of-the-art-ness of this
68    document.
69   </para>
70
71   <para>
72    Skimming through Freshmeat provides mountains of reasons for this
73    HOWTO's existence--the Internet is littered with excellently
74    written and useful programs that have faded away into the Universe
75    of Free Software Forgottenness. This dismal scene made me ask
76    myself, "Why?"
77   </para>
78
79   <para>
80    This HOWTO tries to do a lot of thing (probably too many), but it
81    can't answer that question and won't attempt it. What this HOWTO
82    will attempt to do is give your Free Software project a fighting
83    chance-an edge. If you write a piece of crap that no one is
84    interested in, you can read this HOWTO until you recite it in your
85    sleep and your project will probably fail. Then again, you can
86    write a beautiful, relevent piece of software and follow every
87    instruction in this HOWTO and your software may still not make
88    it. Sometimes life is like that. However, I'll go out a limb and
89    say that if you write a great, relevant pieces of software and
90    ignore the advise in this HOWTO, you'll probably fail <emphasis>
91    more often</emphasis>.
92   </para>
93
94   <para>
95    A lot of the information in this HOWTO is best called common
96    sense. Of course, as any debate on interfaces will prove, what is
97    common sense to some programmers proves totally unintuitive to
98    others. After explaining bites and pieces of this HOWTO to Free
99    Software developers on several occasions, I realized that that
100    writing this HOWTO might provide a useful resource and a forum for
101    programmers to share ideas about what has and has not worked for
102    them. 
103   </para>
104
105   <para>
106
107   </para>
108
109   <para>
110    As anyone involved in any of what seems like an unending parade of
111    ridiculous intellectual property clashes will attest to, a little
112    bit of legalese proves important.
113   </para>
114
115 <!-- Section2: copyright -->
116
117   <sect2 id="copyright">
118    <title>Copyright Information</title>
119
120    <para>
121     This document is copyrighted (c) 2000 Stein Gjoen and is
122     distributed under the terms of the Linux Documentation Project
123     (LDP) license, stated below.  <emphasis>Replace with your name,
124     or supply a new license, when you use this skeleton for a new
125     HOWTO.</emphasis>
126    </para>
127
128    <para>
129     Unless otherwise stated, Linux HOWTO documents are
130     copyrighted by their respective authors. Linux HOWTO documents may
131     be reproduced and distributed in whole or in part, in any medium
132     physical or electronic, as long as this copyright notice is
133     retained on all copies. Commercial redistribution is allowed and
134     encouraged; however, the author would like to be notified of any
135     such distributions.
136    </para>
137
138    <para>
139     All translations, derivative works, or aggregate works
140     incorporating any Linux HOWTO documents must be covered under this
141     copyright notice. That is, you may not produce a derivative work
142     from a HOWTO and impose additional restrictions on its
143     distribution. Exceptions to these rules may be granted under
144     certain conditions; please contact the Linux HOWTO coordinator at
145     the address given below.
146    </para>
147
148    <para>
149     In short, we wish to promote dissemination of this
150     information through as many channels as possible. However, we do
151     wish to retain copyright on the HOWTO documents, and would like to
152     be notified of any plans to redistribute the HOWTOs.
153    </para>
154
155    <para>
156     If you have any questions, please contact 
157     <email>linux-howto@metalab.unc.edu</email>
158    </para>
159   </sect2>
160
161 <!-- Section2: disclaimer -->
162
163   <sect2 id="disclaimer">
164    <title>Disclaimer</title>
165
166    <para>
167     No liability for the contents of this documents can be accepted.
168     Use the concepts, examples and other content at your own risk.
169     As this is a new edition of this document, there may be errors
170     and inaccuracies, that may of course be damaging to your system.
171     Proceed with caution, and although this is highly unlikely,
172     the author(s) do not take any responsibility for that.
173    </para>
174
175    <para>
176     All copyrights are held by their by their respective owners, unless
177     specifically noted otherwise.  Use of a term in this document
178     should not be regarded as affecting the validity of any trademark
179     or service mark.
180    </para>
181
182    <para>
183     Naming of particular products or brands should not be seen 
184     as endorsements.
185    </para>
186
187    <para>
188     You are strongly recommended to take a backup of your system 
189     before major installation and backups at regular intervals.
190    </para>
191   </sect2>
192
193 <!-- Section2: newversions-->
194
195   <sect2 id="newversions">
196    <title>New Versions</title>
197
198     <indexterm>
199      <primary>(your index root)!news on</primary>
200     </indexterm>
201
202    <para>
203     This is the initial release. It is written to be released to
204     developers for critique and brainstorming and submitted to
205     Hampshire College for academic credit. Please keep in mind that
206     this version of the HOWTO is still in an infant stage and will be
207     revised extensively before it hits the LDP.
208    </para>
209
210    <para>
211     The latest version number of this document should always be listed 
212     at my webpage at<ulink url="http://people.debian.org/~mako/">
213     http://people.debian.org/~mako/</unlink> Debian.
214    </para>
215
216    <para>
217     The newest version of this HOWTO will always be made available at
218     the same website, in a variety of formats:
219    </para>
220
221    <para>
222    <itemizedlist>
223     <listitem>
224      <para>
225       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.html">HTML</ulink>.
226      </para>
227     </listitem>
228
229     <listitem>
230      <para>
231        <ulink URL="http://people.debian.org/~mako/howto/fswd-howto.txt">plain text</ulink>.
232      </para>
233     </listitem>
234
235     <listitem>
236      <para>
237       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.US.ps.gz">compressed 
238        postscript (US letter format)</ulink>.
239      </para>
240     </listitem>
241
242     <listitem>
243      <para>
244       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.UF.ps.gz">compressed 
245        postscript (Universal format / 8.27x11in; 210x279mm)</ulink>.
246      </para>
247     </listitem>
248
249     <listitem>
250      <para>
251       <ulink url="http://people.debian.org/~mako/howto/fswd-howto.sgml">SGML source</ulink>.
252      </para>
253     </listitem>
254    </itemizedlist>
255    </para>
256
257 <!-- Section2: credits -->
258
259   <sect2 id="credits">
260    <title>Credits</title>
261
262    <para>
263     In this version I have the pleasure of acknowledging:
264    </para>
265
266    <para>
267     <emphasis>Karl Fogel</emphasis>, the author of <emphasis>Open
268     Source Development with CVS</emphasis> published by the Coriolis
269     Open Press. Larges parts of the book are available <ulink
270     url="http://cvsbook.red-bean.com">on the web</ulink>. 225 pages of
271     the book are available under the GPL and constitute the best
272     tutorial on CVS I have ever seen. The rest of the book covers,
273     "the challenges and philosophical issues inherent in running an
274     Open Source project using CVS." The book does a good job of
275     covering some of the subjects brought up in this HOWTO and much
276     more. <ulink url="http://cvsbook.red-bean.com">The book's
277     website</ulink> has information on ordering the book and provides
278     several translations of the chapters on CVS. I you are seriously
279     interested in running a Free Software project, you want this book.
280    </para>
281    
282    <para>
283     Karl Fogel can be reached at <email>kfogel (at) red-bean (dot)
284     com</email>
285    </para>
286    <para>
287     Also providing support and material, and inspiration for this
288     HOWTO is Eric S. Raymond for his prolific, consitent, and
289     carefully crafted arguments, to Lawrence Lessig for reminding me
290     of the importance of Free Software and to every user and developer
291     involved with the <ulink url="http://www.debian.org">Debian
292     Project</ulink>. The project has provided me with a home, a place
293     to practice Free Software advocacy and to make a difference, a
294     place to learn from those how have been involved with the movement
295     much longer than I, and an proof of a Free Software project that
296     <emphasis>definately, definately works</emphasis>.
297    </para>
298
299    <para>
300     Above all, I want to thank <emphasis>Richard Stallman</emphasis>
301     for his work at the Free Software Foundation and for never giving
302     up. Stallman provided the philosphical basis that attracts me to
303     Free Software and that drives me towards writing a document to
304     make sure it succeeds. RMS can always be emailed at <email>rms
305     (at) gnu (dot) org</email>.
306    </para>
307
308   </sect2>
309
310 <!-- Section2: feedback -->
311
312   <sect2 id="feedback">
313    <title>Feedback</title>
314
315    <para>
316     Feedback is most certainly welcome for this document. Without your
317     submissions and input, this document wouldn't exist. Something
318     missing? Don't hesitate to contact me and to write a chapter. I
319     want this document to be as much a product of the Free Software
320     development process that it heralds and I think its ultimate
321     success will be rooted in this fact. Please send your additions,
322     comments and criticisms to the following email address :
323     <email>mako (at) debian (dot) org</email>.
324    </para>
325    </sect2>
326
327 <!-- Section2: translations -->
328
329   <sect2 id="translations">
330    <title>Translations</title>
331
332    <para>
333     I know that not everyone speaks English. Translations are nice and
334     I'd love for this HOWTO to gain the kind of international reach
335     afforded by a translated version.
336    </para>
337    <para>
338     However, this HOWTO is still young and I have to yet to be
339     contacted about a translation so English is all that is
340     available. If you would like to help with or do a translation, you
341     will gain my utmost respect and admiration and you'll get to be
342     part of a cool process. If you are at all interested, please don't
343     hesitate to contact me at: <email>mako (at) debian (dot)
344     org</email>.
345    </para>
346    </sect2>
347  </sect1>
348
349 <!-- Section1: intro: END -->
350
351 <!-- Section1: starting -->
352
353  <sect1 id="starting">
354   <title>Starting a Project</title>
355
356    <indexterm>
357     <primary>fswd!starting</primary>
358    </indexterm>
359
360
361 <!-- Section2: chooseproject-->
362
363   <sect2 id="chooseproject">
364    <title>Choosing a Project</title>
365   </sect2>
366
367 <!-- Section2: chooselicense-->
368
369   <sect2 id="chooselicense">
370    <title>Deciding on a License</title>
371   </sect2>
372
373 <!-- Section2: chooseversioning-->
374
375   <sect2 id="chooseversioning">
376    <title>Choosing a Method of Version Numbering</title>
377   </sect2>
378
379 <!-- Section2: documentation-->
380
381   <sect2 id="documentation">
382    <title>Documentation</title>
383   </sect2>
384
385 <!-- Section2: presentation -->
386
387   <sect2 id="presentation">
388    <title>Other Presentation Issues</title>
389   </sect2>
390
391 <!-- Section2: futuredev -->
392
393   <sect2 id="futuredev">
394    <title>Nuturing Future Development</title>
395   </sect2>
396
397  </sect1>
398
399 <!-- Section1: starting: END -->
400
401 <!-- Section1: developers -->
402
403  <sect1 id="developers">
404   <title>Maintaining a Project: Interacting with Developers</title>
405
406    <indexterm>
407     <primary>fswd!developers</primary>
408    </indexterm>
409
410 <!-- Section2: delegation  -->
411
412   <sect2 id="delegation">
413    <title>Delegating Work</title>
414   </sect2>
415
416 <!-- Section2: branches  -->
417
418   <sect2 id="branches">
419    <title>Stable and Development Branches</title>
420   </sect2>
421
422 <!-- Section2: freezing -->
423
424   <sect2 id="freezing">
425    <title>Freezing</title>
426   </sect2>
427
428 <!-- Section2: codecram -->
429
430   <sect2 id="codecram">
431    <title>Avoiding the Code Cram Effect</title>
432   </sect2>
433
434 <!-- Section2: patching -->
435
436   <sect2 id="patching">
437    <title>Accepting and Rejecting Patches</title>
438   </sect2>
439  </sect1>
440
441 <!-- Section1: users -->
442
443  <sect1 id="users">
444   <title>Maintaining a Project: Interacting with Users</title>
445
446    <indexterm>
447     <primary>fswd!users</primary>
448    </indexterm>
449
450
451 <!-- Section2: announcing  -->
452
453   <sect2 id="announcing">
454    <title>Announcing Your Project</title>
455   </sect2>
456
457 <!-- Section2: testing -->
458
459   <sect2 id="testing">
460    <title>Testing and Testers</title>
461   </sect2>
462 </sect1>
463
464 <!-- Section1: samples  -->
465
466  <sect1 id="samples">
467   <title>Samples</title>
468
469   <para>
470    <emphasis>This section gives some simple SGML examples you could
471    use. Read the SGML source to see how it was done.</emphasis>
472   </para>
473
474   <para>
475    Further information and examples can be obtained from the publication
476    <ulink url="http://docbook.org/tdg/html/">DocBook: The Definitive 
477    Guide</ulink>. Written by <emphasis>Norman Walsh</emphasis>
478    and <emphasis>Leonard Muellner</emphasis>; 1st Edition, October 1999.
479   </para>
480   
481 <!-- Section2: lists -->
482
483   <sect2 id="lists">
484    <title>Lists</title>
485
486    <para>
487     <emphasis>Lists are used frequently, and are available in a number
488     of formats shown below.</emphasis>
489    </para>
490
491    <para>
492     A list in which each entry is marked with a bullet or other dingbat:
493    </para>
494
495    <para>
496     <itemizedlist>
497
498      <listitem>
499       <para>Apples</para>
500      </listitem>
501
502      <listitem>
503       <para>Oranges</para>
504      </listitem>
505
506      <listitem>
507       <para>Bananas</para>
508      </listitem>
509
510     </itemizedlist>
511    </para>
512
513    <para>
514     A list in which each entry is composed of a set of one or more
515     terms and an associated description:
516    </para>
517
518    <para>
519     <variablelist>
520
521      <varlistentry>
522       <term>Fruits</term>
523       <listitem>
524        <para>such as apples, oranges, and more.</para>
525       </listitem>
526      </varlistentry>
527
528      <varlistentry>
529       <term>Nuts</term>
530       <listitem>
531        <para>Don't eat too many; you are what you eat.</para>
532       </listitem>
533      </varlistentry>
534
535      <varlistentry>
536       <term>Vegetables</term>
537       <listitem>
538        <para>Potatos are spelled with care.</para>
539       </listitem>
540      </varlistentry>
541
542     </variablelist>
543    </para>
544
545    <para>
546     A list in which each entry is marked with a sequentially 
547     incremented label:
548    </para>
549
550    <para>
551      <orderedlist>
552
553       <listitem>
554        <para>Step one</para>
555       </listitem>
556
557       <listitem>
558        <para>Step two</para>
559       </listitem>
560
561      </orderedlist>
562    </para>
563   </sect2>
564
565 <!-- Section2: links -->
566
567   <sect2 id="links">
568    <title>Links</title>
569
570    <para>
571     <emphasis>Links can be used within your documents to refer to
572     different sections and chapters or to refer to documents external
573     to yours.</emphasis>
574    </para>
575
576    <sect3 id="int-links">
577     <title>Internal links</title>
578
579     <para>
580      Click on the <xref LinkEnd="samples"> link to jump to the top of
581      this chapter. Note the anchor at the section tag.
582     </para>
583    </sect3>
584
585    <sect3 id="ext-links">
586     <title>External links</title>
587
588     <para>
589      Click on <ulink url="http://www.linuxdoc.org/">this</ulink> link
590      to jump to the LDP site. Note you can use http, ftp, news and
591      other protocols in the locator if required.
592     </para>
593    </sect3>
594
595   </sect2>
596
597 <!-- Section2: images -->
598
599   <sect2 id="images">
600    <title>Images</title>
601
602    <para>
603     <emphasis>Avoid diagrams if possible as this cannot be rendered
604     in the ASCII outputs which are still needed by many around the
605     world.</emphasis>
606    </para>
607
608    <para>
609      <figure>
610       <title>Graphics Test Image</title>
611       <graphic FileRef="red.gif"></graphic>
612      </figure>
613    </para>
614
615    <para>
616     Here is another variation which allows for ALT text:
617    </para>
618
619    <para>
620      <mediaobject>
621
622       <imageobject>
623        <imagedata fileref="green.gif" format="gif">
624       </imageobject>
625
626       <textobject>
627        <phrase>
628         ALT text to be used: Green Ball
629        </phrase>
630       </textobject>
631
632       <caption>
633        <para>
634         Caption for the graphic goes here: This is a Green Ball.
635        </para>
636       </caption>
637      </mediaobject>
638    </para>
639   </sect2>
640
641  </sect1>
642
643 <!-- Section1: samples: END -->
644
645
646 <!-- Section1: structure -->
647
648  <sect1 id="structure">
649   <title>Structure</title>
650
651   <para>
652    <emphasis>A quick overview on how all parts fit together in the overall
653    structure. An example from the Multi Disk HOWTO is used.</emphasis>
654  </para>
655
656   <para>
657    As this type of document is supposed to be as much for learning as
658    a technical reference document I have rearranged the structure to
659    this end. For the designer of a system it is more useful to have
660    the information presented in terms of the goals of this exercise
661    than from the point of view of the logical layer structure of the
662    devices themselves. Nevertheless this document would not be
663    complete without such a layer structure the computer field is so
664    full of, so I will include it here as an introduction to how it
665    works.
666   </para>
667
668 <!-- Section2: logical-struct -->
669
670   <sect2 id="logical-struct">
671    <title>Logical structure</title>
672
673     <indexterm>
674      <primary>disk!structure, I/O subsystem</primary>
675     </indexterm>
676
677    <para>
678     This is based on how each layer access each other, traditionally
679     with the application on top and the physical layer on the bottom.
680     It is quite useful to show the interrelationship between each of
681     the layers used in controlling drives.
682
683     <screen>
684         ___________________________________________________________
685         |__     File structure          ( /usr /tmp etc)        __|
686         |__     File system             (ext2fs, vfat etc)      __|
687         |__     Volume management       (AFS)                   __|
688         |__     RAID, concatenation     (md)                    __|
689         |__     Device driver           (SCSI, IDE etc)         __|
690         |__     Controller              (chip, card)            __|
691         |__     Connection              (cable, network)        __|
692         |__     Drive                   (magnetic, optical etc) __|
693         -----------------------------------------------------------
694     </screen>
695    </para>
696
697    <para>
698     In the above diagram both volume management and RAID and
699     concatenation are optional layers. The 3 lower layers are in
700     hardware. All parts are discussed at length later on in this
701     document.
702    </para>
703   </sect2>
704
705 <!-- Section2: doc-struct -->
706
707   <sect2 id="doc-struct">
708    <title>Document structure</title>
709
710    <para>
711     Most users start out with a given set of hardware and some plans
712     on what they wish to achieve and how big the system should be.
713     This is the point of view I will adopt in this document in
714     presenting the material, starting out with hardware, continuing
715     with design constraints before detailing the design strategy that
716     I have found to work well. I have used this both for my own
717     personal computer at home, a multi purpose server at work and
718     found it worked quite well. In addition my Japanese co-worker in
719     this project have applied the same strategy on a server in an
720     academic setting with similar success.
721    </para>
722
723    <para>
724     Finally at the end I have detailed some configuration tables for
725     use in your own design. If you have any comments regarding this
726     or notes from your own design work I would like to hear from you
727     so this document can be upgraded.
728    </para>
729   </sect2>
730
731 <!-- Section2: reading-plan -->
732
733   <sect2 id="reading-plan">
734    <title>Reading plan</title>
735
736    <para>
737     <emphasis>As you go beyond 50 pages or so there will be a lot of
738     text that experts and even the experienced do not need to read.
739     Keeping in mind that we wish to care for all kinds of people in
740     the Linux world we might have to make a reading plan. Again,
741     an example follows from the Multi Disk HOWTO.</emphasis>
742    </para>
743
744    <para>
745     Although not the biggest HOWTO it is nevertheless rather big
746     already and I have been requested to make a reading plan to make
747     it possible to cut down on the volume.
748    </para>
749
750    <para>
751     <variablelist>
752
753      <varlistentry>
754       <term>Expert</term>
755       <listitem>
756        <para>
757         (aka the elite). If you are familiar with Linux as well as
758         disk drive technologies you will find most of what you need in
759         the appendices. Additionally you are recommended to read the
760         FAQ and the <XRef LinkEnd="bits-n-pieces">chapter.
761        </para>
762       </listitem>
763      </varlistentry>
764
765      <varlistentry>
766       <term>Experienced</term>
767       <listitem>
768        <para>
769         (aka Competent). If you are familiar with computers in
770         general you can go straight to the chapters on 
771         <XRef LinkEnd="technologies"> and continue from there on.
772        </para>
773       </listitem>
774      </varlistentry>
775
776      <varlistentry>
777       <term>Newbie</term>
778       <listitem>
779        <para>
780         (mostly harmless). You just have to read the whole thing.
781         Sorry. In addition you are also recommended to read all the
782         other disk related HOWTOs.
783        </para>
784       </listitem>
785      </varlistentry>
786
787     </variablelist>
788    </para>
789   </sect2>
790
791  </sect1>
792
793 <!-- Section1: structure: END -->
794
795
796 <!-- Section1: technologies -->
797
798  <sect1 id="technologies">
799   <title>Technologies</title>
800
801    <indexterm>
802     <primary>(your index root)!technologies</primary>
803    </indexterm>
804
805   <para>
806    <emphasis>Introduction of technology for the newbie with a few
807    references to detailed works. Remember that not everyone has
808    Internet access so you have to explain in sufficient details so
809    even the newbie can get by.</emphasis>
810   </para>
811
812  </sect1>
813
814 <!-- Section1: technologies: END -->
815
816
817 <!-- Section1: implement -->
818
819  <sect1 id="implement">
820   <title>Implementation</title>
821
822    <indexterm>
823     <primary>(your index root)!implementation</primary>
824    </indexterm>
825
826   <para>
827    <emphasis>Now your readers should have a sufficient knowledge of
828    what this is about and now we come to the hands on of implementing
829    your clever scheme.</emphasis>
830   </para>
831
832  </sect1>
833
834 <!-- Section1: implement: END -->
835
836
837 <!-- Section1: maint -->
838
839  <sect1 id="maint">
840   <title>Maintenance</title>
841
842    <indexterm>
843     <primary>(your index root)!maintenance</primary>
844    </indexterm>
845
846   <para>
847    <emphasis>Few systems and designs are maintenance free, here you
848    explain how to keep the system running.</emphasis>
849   </para>
850
851  </sect1>
852
853 <!-- Section1: maint: END -->
854
855
856 <!-- Section1: adv-issues -->
857
858  <sect1 id="adv-issues">
859   <title>Advanced Issues</title>
860
861    <indexterm>
862     <primary>(your index root)!advanced topics</primary>
863    </indexterm>
864
865   <para>
866    <emphasis>You can get most things up and running in a quick and
867    dirty fashion, useful for testing and getting used to how things
868    work. For more serious use you would need to be a little more
869    advanced. This is the place to explain it all, if applicable.</emphasis>
870   </para>
871
872  </sect1>
873
874 <!-- Section1: adv-issues: END -->
875
876
877 <!-- Section1: moreinfo -->
878
879  <sect1 id="moreinfo">
880   <title>Further Information</title>
881
882    <indexterm>
883     <primary>(your index root)!information resources</primary>
884    </indexterm>
885
886   <para>
887    <emphasis>A HOWTO cannot describe everything, some times the user
888    has to venture out on th enet to get more information or just
889    updates. Here is the place to tell where and how. Again examples
890    from the Multi Disk HOWTO, replace as needed.</emphasis> There is wealth
891    of information one should go through when setting up a major system,
892    for instance for a news or general Internet service provider.  The
893    FAQs in the following groups are useful:
894   </para>
895
896 <!-- Section2: newsgroups -->
897
898   <sect2 id="newsgroups">
899    <title>News groups</title>
900
901     <indexterm>
902      <primary>disk!information resources!news groups</primary>
903     </indexterm>
904
905    <para>Some of the most interesting news groups are:
906
907     <itemizedlist>
908
909      <listitem>
910       <para>
911        <ulink url="news:comp.arch.storage">Storage</ulink>.
912       </para>
913      </listitem>
914
915      <listitem>
916       <para>
917        <ulink url="news:comp.sys.ibm.pc.hardware.storage">PC storage</ulink>.
918       </para>
919      </listitem>
920
921      <listitem>
922       <para>
923        <ulink url="news:alt.filesystems.afs">AFS</ulink>.
924       </para>
925      </listitem>
926
927      <listitem>
928       <para>
929        <ulink url="news:comp.periphs.scsi">SCSI</ulink>.
930       </para>
931      </listitem>
932
933      <listitem>
934       <para>
935        <ulink url="news:comp.os.linux.setup">Linux setup</ulink>.
936       </para>
937      </listitem>
938
939     </itemizedlist>
940    </para>
941
942    <para>
943     Most newsgroups have their own FAQ that are designed to answer most
944     of your questions, as the name Frequently Asked Questions indicate.
945     Fresh versions should be posted regularly to the relevant newsgroups.
946     If you cannot find it in your news spool you could go directly to the
947     <ulink url="ftp://rtfm.mit.edu/">FAQ main archive FTP site</ulink>.
948     The WWW versions can be browsed at the 
949     <ulink url="http://www.cis.ohio-state.edu/hypertext/faq/usenet/FAQ-List.html">FAQ
950     main archive WWW site</ulink>.
951    </para>
952
953    <para>
954     Some FAQs have their own home site, of particular interest:
955
956     <itemizedlist>
957
958      <listitem>
959       <para>
960        <ulink url="http://www.paranoia.com/~filipg/HTML/LINK/F_SCSI.html">SCSI FAQ</ulink> 
961        and
962       </para>
963      </listitem>
964
965      <listitem>
966       <para>
967        <ulink url="http://alumni.caltech.edu/~rdv/comp_arch_storage/FAQ-1.html">comp.arch.storage FAQ</ulink>.
968       </para>
969      </listitem>
970
971     </itemizedlist>
972    </para>
973   </sect2>
974
975 <!-- Section2: maillists -->
976
977   <sect2 id="maillists">
978    <title>Mailing Lists</title>
979
980     <indexterm>
981      <primary>disk!information resources!mailing lists</primary>
982     </indexterm>
983
984    <para>
985     These are low-noise channels mainly for developers. Think twice
986     before asking questions there as noise delays the development.
987     Some relevant lists are <email>linux-raid</email>,
988     <email>linux-scsi</email> and <email>linux-ext2fs</email>.  Many
989     of the most useful mailing lists run on the <Literal
990     remap="tt">vger.rutgers.edu</Literal> server but this is
991     notoriously overloaded, so try to find a mirror. There are some
992     lists mirrored at <ulink url="http://www.redhat.com">The Redhat
993     Home Page</ulink>. Many lists are also accessible at <ulink
994     url="http://www.linuxhq.com/lnxlists">linuxhq</ulink>, and the
995     rest of the web site contains useful information as well.
996    </para>
997
998    <para>
999     If you want to find out more about the lists available you can send
1000     a message with the line <command>lists</command> to the list server
1001     at <email>majordomo@vger.rutgers.edu</email>.
1002     If you need help on how to use the mail server just send the line
1003     <command>help</command> to the same address.  Due to the
1004     popularity of this server it is likely it takes a bit to time before
1005     you get a reply or even get messages after you send a
1006     <command>subscribe</command> command.
1007    </para>
1008
1009    <para>
1010     There is also a number of other majordomo list servers that can
1011     be of interest such as the EATA driver list
1012     (<email>linux-eata@mail.uni-mainz.de</email>)
1013     and the Intelligent IO list <email>linux-i2o@dpt.com</email>.
1014    </para>
1015
1016    <para>
1017     Mailing lists are in a state of flux but you can find links to a
1018     number of interesting lists from the 
1019     <ulink url="http://www.linuxdoc.org/">Linux Documentation
1020     Homepage</ulink>.
1021    </para>
1022   </sect2>
1023
1024 <!-- Section2: howto -->
1025
1026   <sect2 id="howto">
1027    <title>HOWTO</title>
1028
1029     <indexterm>
1030      <primary>disk!information resources!HOWTOs</primary>
1031     </indexterm>
1032
1033    <para>
1034     These are intended as the primary starting points to get the
1035     background information as well as show you how to solve a
1036     specific problem. Some relevant HOWTOs are
1037     <Literal remap="tt">Bootdisk</Literal>, 
1038     <Literal remap="tt">Installation</Literal>,
1039     <Literal remap="tt">SCSI</Literal> and 
1040     <Literal remap="tt">UMSDOS</Literal>.  The main site for these is the
1041     <ulink url="http://www.linuxdoc.org/">LDP archive</ulink>at
1042     Metalab (formerly known as Sunsite).
1043    </para>
1044
1045    <para>
1046     There is a a new HOWTO out that deals with setting up a DPT RAID
1047     system, check out the
1048     <ulink url="http://www.ram.org/computing/linux/dpt_raid.html">DPT RAID
1049     HOWTO homepage</ulink>.
1050    </para>
1051   </sect2>
1052
1053 <!-- Section2: local-res -->
1054
1055   <sect2 id="local-res">
1056    <title>Local Resources</title>
1057
1058     <indexterm>
1059      <primary>disk!information resources!local</primary>
1060     </indexterm>
1061
1062    <para>
1063     In most distributions of Linux there is a document directory
1064     installed, have a look in the <filename>/usr/doc</filename>
1065     directory. where most packages store their main documentation and
1066     README files etc.  Also you will here find the HOWTO archive 
1067     (<filename>/usr/doc/HOWTO</filename>) of ready formatted HOWTOs
1068     and also the mini-HOWTO archive 
1069     (<filename>/usr/doc/HOWTO/mini</filename>) of plain text
1070     documents.
1071    </para>
1072
1073    <para>
1074     Many of the configuration files mentioned earlier can be found in
1075     the <filename>/etc</filename> directory. In particular you will
1076     want to work with the <filename>/etc/fstab</filename> file that
1077     sets up the mounting of partitions and possibly also
1078     <filename>/etc/raidtab</filename> file that is used for the
1079     <Literal remap="tt">md</Literal> system to set up RAID.
1080    </para>
1081
1082    <para>
1083     The kernel source in <filename>/usr/src/linux</filename> is, of
1084     course, the ultimate documentation. In other words, <quote>use
1085     the source, Luke</quote>. It should also be pointed out that the
1086     kernel comes not only with source code which is even commented
1087     (well, partially at least) but also an informative
1088     <filename>/usr/src/linux/Documentation</filename>. If you are
1089     about to ask any questions about the kernel you should read this
1090     first, it will save you and many others a lot of time and
1091     possibly embarrassment.
1092    </para>
1093
1094    <para>
1095     Also have a look in your system log file
1096     (<filename>/var/log/messages</filename>) to see what is going on
1097     and in particular how the booting went if too much scrolled off
1098     your screen. Using <command>tail -f /var/log/messages</command>
1099     in a separate window or screen will give you a continuous update
1100     of what is going on in your system.
1101    </para>
1102
1103    <para>
1104     You can also take advantage of the  <filename>/proc</filename>
1105     file system that is a window into the inner workings of your
1106     system. Use <command>cat</command> rather than
1107     <command>more</command> to view the files as they are reported as
1108     being zero length. Reports are that <command>less</command> works
1109     well here.
1110    </para>
1111   </sect2>
1112
1113 <!-- Section2: web -->
1114
1115   <sect2 id="web">
1116    <title>Web Sites</title>
1117
1118     <indexterm>
1119      <primary>disk!information resources!WWW</primary>
1120     </indexterm>
1121     <indexterm>
1122      <primary>disk!information resources!web pages</primary>
1123     </indexterm>
1124
1125    <para>
1126     There are a huge number of informative web sites available. By
1127     their very nature they change quickly so do not be surprised
1128     if these links become quickly outdated.
1129    </para>
1130
1131    <para>
1132     A good starting point is of course the 
1133     <ulink url="http://www.linuxdoc.org/">Linux Documentation
1134     Project</ulink> home page, an information central for
1135     documentation, project pages and much more.
1136    </para>
1137
1138    <para>
1139     Please let me know if you have any other leads that can be 
1140     of interest.
1141    </para>
1142   </sect2>
1143
1144  </sect1>
1145
1146 <!-- Section1: moreinfo: END -->
1147
1148
1149 <!-- Section1: help -->
1150
1151  <sect1 id="help">
1152   <title>Getting Help</title>
1153
1154    <indexterm>
1155     <primary>(your index root)!assistance, obtaining</primary>
1156    </indexterm>
1157
1158   <para>
1159    In the end you might find yourself unable to solve your problems
1160    and need help from someone else. The most efficient way is either
1161    to ask someone local or in your nearest Linux user group, search
1162    the web for the nearest one.
1163   </para>
1164
1165   <para>
1166    Another possibility is to ask on Usenet News in one of the many,
1167    many newsgroups available. The problem is that these have such a
1168    high volume and noise (called low signal-to-noise ratio) that your
1169    question can easily fall through unanswered.
1170   </para>
1171
1172   <para>
1173    No matter where you ask it is important to ask well or you will
1174    not be taken seriously. Saying just <emphasis remap="it">my disk
1175    does not work</emphasis> is not going to help you and instead the
1176    noise level is increased even further and if you are lucky someone
1177    will ask you to clarify.
1178   </para>
1179
1180   <para>
1181    Instead describe your problems in some detail that will enable
1182    people to help you. The problem could lie somewhere you did not
1183    expect. Therefore you are advised to list the following information
1184    about your system:
1185   </para>
1186
1187   <para>
1188    <variablelist>
1189
1190     <varlistentry>
1191      <term>Hardware</Term>
1192      <listitem>
1193       <para>
1194        <itemizedlist>
1195         <listitem>
1196          <para>Processor</para>
1197         </listitem>
1198
1199         <listitem>
1200          <para>DMA</para>
1201         </listitem>
1202
1203         <listitem>
1204          <para>IRQ</para>
1205         </listitem>
1206
1207         <listitem>
1208          <para>Chip set (LX, BX etc)</para>
1209         </listitem>
1210
1211         <listitem>
1212          <para>Bus (ISA, VESA, PCI etc)</para>
1213         </listitem>
1214
1215         <listitem>
1216          <para>
1217           Expansion cards used (Disk controllers, video, IO 
1218           etc.)
1219          </para>
1220         </listitem>
1221
1222        </itemizedlist>
1223       </para>
1224      </listitem>
1225     </varlistentry>
1226
1227     <varlistentry>
1228      <term>Software</term>
1229      <listitem>
1230       <para>
1231        <itemizedlist>
1232
1233         <listitem>
1234          <para>BIOS (On motherboard and possibly SCSI host adapters)</para>
1235         </listitem>
1236
1237         <listitem>
1238          <para>LILO, if used</para>
1239         </listitem>
1240
1241         <listitem>
1242          <para>
1243           Linux kernel version as well as possible modifications 
1244           and patches
1245          </para>
1246         </listitem>
1247
1248         <listitem>
1249          <para>Kernel parameters, if any</para>
1250         </listitem>
1251
1252         <listitem>
1253          <para>
1254           Software that shows the error (with version number 
1255           or date)
1256          </para>
1257         </listitem>
1258
1259        </itemizedlist>
1260       </para>
1261
1262      </listitem>
1263     </varlistentry>
1264
1265     <varlistentry>
1266      <term>Peripherals</term>
1267      <listitem>
1268       <para>
1269        <itemizedlist>
1270
1271         <listitem>
1272          <para>
1273           Type of disk drives with manufacturer name, version and type
1274          </para>
1275         </listitem>
1276
1277         <listitem>
1278          <para>Other relevant peripherals</para>
1279         </listitem>
1280
1281        </itemizedlist>
1282       </para>
1283      </listitem>
1284     </varlistentry>
1285
1286    </variablelist>
1287   </para>
1288
1289   <para>
1290    Remember that booting text is logged to
1291    <filename>/var/log/messages</filename> which can answer most of
1292    the questions above. Obviously if the drives fail you might not be
1293    able to get  the log saved to disk but you can at least scroll
1294    back up the screen using the <keycap>SHIFT</keycap> and
1295    <keycap>PAGE UP</keycap> keys. It may also be useful to include
1296    part of this in your request for help but do not go overboard,
1297    keep it <emphasis>brief</emphasis> as a complete log file dumped
1298    to Usenet News is more than a little annoying.
1299   </para>
1300
1301  </sect1>
1302
1303 <!-- Section1: help: END -->
1304
1305
1306 <!-- Section1: remarks -->
1307
1308  <sect1 id="remarks">
1309   <title>Concluding Remarks</title>
1310
1311    <indexterm>
1312     <primary>(your index root)!conclusion</primary>
1313    </indexterm>
1314
1315   <para>
1316    <emphasis>Just summing up... Also a place for general
1317    recommendations.</emphasis>
1318   </para>
1319
1320  </sect1>
1321
1322 <!-- Section1: remarks: END -->
1323
1324
1325 <!-- Section1: faq -->
1326
1327  <sect1 id="faq">
1328   <title>Questions and Answers</title>
1329
1330    <indexterm>
1331     <primary>(your index root)!FAQ</primary>
1332    </indexterm>
1333    <indexterm>
1334     <primary>(your index root)!frequently asked questions</primary>
1335    </indexterm>
1336
1337   <para>
1338    <emphasis>Check the newsgroups and try to determine some frequent
1339    problems and cover them here. Again an example from the Multi Disk
1340    HOWTO.</emphasis>
1341   </para>
1342
1343   <para>
1344    This is just a collection of what I believe are the most common
1345    questions people might have. Give me more feedback and I will turn
1346    this section into a proper FAQ.
1347   </para>
1348
1349   <para>
1350    <itemizedlist>
1351     <listitem>
1352      <para>
1353       Q:How many physical disk drives (spindles) does a Linux system need?
1354      </para>
1355
1356      <para>
1357       A: Linux can run just fine on one drive (spindle).  Having
1358       enough  RAM (around 32 MB, and up to 64 MB) to support swapping
1359       is a  better price/performance choice than getting a second
1360       disk. (E)IDE disk is usually cheaper (but a little slower) than
1361       SCSI.
1362      </para>
1363     </listitem>
1364
1365     <listitem>
1366      <para>
1367       Q: Are there any disadvantages in this scheme?
1368      </para>
1369
1370      <para>
1371       A: There is only a minor snag: if even a single partition
1372       overflows the system might stop working properly. The severity
1373       depends of course on what partition is affected. Still this is
1374       not hard to monitor, the command <command>df</command> gives
1375       you a good overview of the situation. Also check the swap
1376       partition(s) using <command>free</command> to make sure you are
1377       not about to run out of virtual memory.
1378      </para>
1379     </listitem>
1380
1381     <listitem>
1382      <para>
1383       Q: OK, so should I split the system into as many partitions as 
1384       possible for a single drive?
1385      </para>
1386
1387      <para>
1388       A: No, there are several disadvantages to that. First of all
1389       maintenance becomes needlessly complex and you gain very little
1390       in this. In fact if your partitions are too big you will seek
1391       across larger areas than needed. This is a balance and
1392       dependent on the number of physical drives you have.
1393      </para>
1394     </listitem>
1395
1396    </itemizedlist>
1397
1398    <comment>
1399     Greg Leblanc:  Depending on how big this FAQ gets, perhaps it
1400     would be worthwhile to have, say, the 5 most FAQ, and put the
1401     rest into an external FAQ.  Dunno.  Comments?
1402    </comment>
1403
1404    <emphasis>(rest deleted.)</emphasis>
1405   </para>
1406
1407  </sect1>
1408
1409 <!-- Section1: faq: END -->
1410
1411
1412 <!-- Section1: bits-n-pieces -->
1413
1414  <sect1 id="bits-n-pieces">
1415   <title>Bits and Pieces </title>
1416
1417    <indexterm>
1418     <primary>disk!miscellaneous</primary>
1419    </indexterm>
1420
1421   <para>
1422    This is basically a section where I stuff all the bits I have not
1423    yet decided where should go, yet that I feel is worth knowing
1424    about. It is a kind of transient area.
1425   </para>
1426
1427  </sect1>
1428
1429 <!-- Section1: bits-n-pieces: END -->
1430
1431
1432 <!-- Section1: examples -->
1433
1434  <sect1 id="examples">
1435   <title>Examples</title>
1436
1437    <indexterm>
1438     <primary>(your index root)!examples</primary>
1439    </indexterm>
1440
1441   <para>
1442    <emphasis>Example designs and sample configuration files and other
1443    relevant details is always handy</emphasis>
1444   </para>
1445
1446  </sect1>
1447
1448 <!-- Section1: examples: END -->
1449
1450 </article>
1451
1452 <!-- Keep this comment at the end of the file
1453 Local variables:
1454 mode: sgml
1455 sgml-omittag:t
1456 sgml-shorttag:t
1457 sgml-namecase-general:t
1458 sgml-general-insert-case:lower
1459 sgml-minimize-attributes:nil
1460 sgml-always-quote-attributes:t
1461 sgml-indent-step:1
1462 sgml-indent-data:nil
1463 sgml-parent-document:nil
1464 sgml-exposed-tags:nil
1465 sgml-local-catalogs:nil
1466 sgml-local-ecat-files:nil
1467 End:
1468 -->

Benjamin Mako Hill || Want to submit a patch?