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

Benjamin Mako Hill || Want to submit a patch?