I'd love for this HOWTO to gain the kind of international reach
afforded by a translated version.
</para>
+
<para>
However, this HOWTO is still young and I have to yet to be
contacted about a translation so English is all that is currently
<term>README or Readme</term>
<listitem>
- <para>
- A document containing all the basic installation,
- compilation, and even basic use instructions that make up
- the bare minimum information needed to get the program up and
- running. A README is not your chance to be verbose but needs
- to be concise and effective. An ideal README is at least 30
- lines long and more no more than 250.
- </para>
+ <para>A document containing all the basic installation,
+ compilation, and even basic use instructions that make up the
+ bare minimum information needed to get the program up and
+ running. A README is not your chance to be verbose but needs
+ to be concise and effective. An ideal README is at least 30
+ lines long and more no more than 250.</para>
</listitem>
</varlistentry>
<term>INSTALL or Install</term>
<listitem>
- <para>
- The INSTALL file should be much shorter than the INSTALL file
- and should quickly and concisely describe how to build and
- install the program. Usually an install simply instructs the
- user to run ./configure; make; make install and touches on
- any unusual options that may be necessary. More advanced
- users can usually avoid them but it's good practice to at
- least glance at the file to understand what can be
- expected. For most relatively standard install procedures and
- for most programs, INSTALL files are as short as possible are
- rarely over 100 lines.
- </para>
+ <para>The INSTALL file should be much shorter than the INSTALL
+ file and should quickly and concisely describe how to build
+ and install the program. Usually an install simply instructs
+ the user to run ./configure; make; make install and touches on
+ any unusual options that may be necessary. More advanced users
+ can usually avoid them but it's good practice to at least
+ glance at the file to understand what can be expected. For
+ most relatively standard install procedures and for most
+ programs, INSTALL files are as short as possible are rarely
+ over 100 lines.</para>
</listitem>
</varlistentry>
<term>Changelog, ChangeLog, CHANGELOG, or changelog</term>
<listitem>
- <para>
- A changelog is a simple file that every well-managed free
- software project should include. A changelog is simple the
- file that, as its name would imply, logs or documents the
- changes to a program. The most simple way to do a changelog
- is to simply keep a file with the source code for your
- program and add a section to the top of the changelog with
- each release describing what has been, changed, fixed, or
- added to the program. It's a good idea to post the changelog
- onto the website as well because it can help people decide
- whether they want or need to upgrade to a newer version or
- wait for a more significant upgrade.
- </para>
+ <para>A changelog is a simple file that every well-managed
+ free software project should include. A changelog is simple
+ the file that, as its name would imply, logs or documents the
+ changes to a program. The most simple way to do a changelog is
+ to simply keep a file with the source code for your program
+ and add a section to the top of the changelog with each
+ release describing what has been, changed, fixed, or added to
+ the program. It's a good idea to post the changelog onto the
+ website as well because it can help people decide whether they
+ want or need to upgrade to a newer version or wait for a more
+ significant upgrade.</para>
</listitem>
</varlistentry>
<term><acronym>FAQ</acronym></term>
<listitem>
- <para>
- For those of you that don't already
- know. <acronym>FAQ</acronym> stands for Frequently Asked
- Questions and the file is a collection of exactly that. FAQs
- are not difficult to make. Simply make a policy that if you
- are asked a question or see a question on a mailing list two
- or more times, add it the question (and its answer) to your
- FAQs. FAQs are more optional than the files listed above but
- they can save your time, increase usability, and decrease
- headaches on all sides.
- </para>
+ <para>For those of you that don't already
+ know. <acronym>FAQ</acronym> stands for Frequently Asked
+ Questions and the file is a collection of exactly that. FAQs
+ are not difficult to make. Simply make a policy that if you
+ are asked a question or see a question on a mailing list two
+ or more times, add it the question (and its answer) to your
+ FAQs. FAQs are more optional than the files listed above but
+ they can save your time, increase usability, and decrease
+ headaches on all sides.</para>
</listitem>
</varlistentry>
</sect3>
<sect3>
- <title>Website</title>
+ <title>Website</title>
<para>
It's only a sort of an issue of documentation but a good website
is quickly becoming an essential part of any free software
<varlistentry>
<term>Minimize the number of branches</term>
<listitem>
- <para>
- Debian may be able to make good use of four or five branches
- but it contains gigabytes of software in over 5000 packages
- compiled for a 5-6 different architectures. Two is a good
- number. Too many branches will confuse your users (I can't
- count how many times I had to describe Debian's system when it
- only had 2 and sometimes 3 branches!), potential developers
- and even yourself. Branches can help but they come at a cost
- so use them very sparingly.
- </para>
+ <para>Debian may be able to make good use of four or five
+ branches but it contains gigabytes of software in over 5000
+ packages compiled for a 5-6 different architectures. Two is a
+ good number. Too many branches will confuse your users (I can't
+ count how many times I had to describe Debian's system when it
+ only had 2 and sometimes 3 branches!), potential developers and
+ even yourself. Branches can help but they come at a cost so use
+ them very sparingly.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>Make sure that all your different branches are explained</term>
<listitem>
- <para>
- As I mentioned in the preceding paragraph, different branches
- <emphasis>will</emphasis> confuse your users. Do everything
- you can to avoid this by clearly explaining the different
- branches in a prominent page on your website and in a Readme
- file in the <acronym>FTP</acronym> or <acronym>HTTP</acronym>
- directory.
- </para>
+ <para>As I mentioned in the preceding paragraph, different
+ branches <emphasis>will</emphasis> confuse your users. Do
+ everything you can to avoid this by clearly explaining the
+ different branches in a prominent page on your website and in a
+ Readme file in the <acronym>FTP</acronym> or
+ <acronym>HTTP</acronym> directory.</para>
<para>
I might also recommend against a mistake that I think Debian
<varlistentry>
<term>Make sure all your branches are always available</term>
<listitem>
- <para>
- Like a lot of document, this should probably should go without
- saying but experience has taught me that it's not always
- obvious to people. It's a good idea to physically split up
- different branches in different directories or directory trees
- on your <acronym>FTP</acronym> or <acronym>HTTP</acronym>
- site. Linux accomplishes this by having all the v2.2 and a
- v2.3 subdirectory where it is immediately obvious (after you
- know their version numbering scheme) which directory is the
- most recent stable and the current development
- releases. Debian accomplishes this by naming all their
- distribution by name and then changing symlinks named
- <quote>stable,</quote> <quote>unstable</quote> and
- <quote>frozen</quote> to point to which ever distribution (by
- name) is in whatever stage. Both methods work and their are
- others. In any case, it is important that different branches
- are always available, are accessible from consistent
- locations, and that different branches are clearly
- distinguished from each other so your users know exactly what
- they want to be downloading and where to get it.
- </para>
+ <para>Like a lot of document, this should probably should go
+ without saying but experience has taught me that it's not
+ always obvious to people. It's a good idea to physically split
+ up different branches in different directories or directory
+ trees on your <acronym>FTP</acronym> or <acronym>HTTP</acronym>
+ site. Linux accomplishes this by having all the v2.2 and a v2.3
+ subdirectory where it is immediately obvious (after you know
+ their version numbering scheme) which directory is the most
+ recent stable and the current development releases. Debian
+ accomplishes this by naming all their distribution by name and
+ then changing symlinks named <quote>stable,</quote>
+ <quote>unstable</quote> and <quote>frozen</quote> to point to
+ which ever distribution (by name) is in whatever stage. Both
+ methods work and their are others. In any case, it is important
+ that different branches are always available, are accessible
+ from consistent locations, and that different branches are
+ clearly distinguished from each other so your users know
+ exactly what they want to be downloading and where to get
+ it.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>alpha releases</term>
<listitem>
- <para>
- Alpha releases are expected to be unstable, perhaps a little
- unsafe, but definitely usable. Alpha versions should have
- full functionality and limited testing. They can have known
- bugs and kinks that have yet to be worked out. Before sure to
- keep in mind that <emphasis>alpha releases are still
- releases</emphasis> and people are not going to be expecting
- a nightly build from the CVS source. An alpha should work and
- have minimal testing and bug fixing already finished.
- </para>
+ <para>Alpha releases are expected to be unstable, perhaps a
+ little unsafe, but definitely usable. Alpha versions should
+ have full functionality and limited testing. They can have
+ known bugs and kinks that have yet to be worked out. Before
+ sure to keep in mind that <emphasis>alpha releases are still
+ releases</emphasis> and people are not going to be expecting a
+ nightly build from the CVS source. An alpha should work and
+ have minimal testing and bug fixing already finished.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>beta releases</term>
<listitem>
- <para>
- Beta releases are general expected to be usable and
- slightly unstable, although definitely
- <emphasis>not</emphasis> unsafe. Beta releases usually
- preclude a full release by under a month. They can contain
- small known bugs but no major ones. All major functionality
- should be fully implemented although the exact mechanics can
- still be worked out. Beta releases are great tool to whet the
- appetites of potential users by giving them a very
- realistic view of where your project is going in the very
- near future and can help keep interest by giving people
- <emphasis>something.</emphasis>
- </para>
+ <para>Beta releases are general expected to be usable and
+ slightly unstable, although definitely
+ <emphasis>not</emphasis> unsafe. Beta releases usually
+ preclude a full release by under a month. They can contain
+ small known bugs but no major ones. All major functionality
+ should be fully implemented although the exact mechanics can
+ still be worked out. Beta releases are great tool to whet the
+ appetites of potential users by giving them a very realistic
+ view of where your project is going in the very near future
+ and can help keep interest by giving people
+ <emphasis>something.</emphasis></para>
</listitem>
</varlistentry>
<varlistentry>
<term>development releases</term>
<listitem>
- <para>
- Development release is much more vague term than
- <quote>alpha</quote> or <quote>beta</quote>. I usually choose
- to reserve the term for discussion of a development
- branch. There are other ways to use the term. So many in
- fact, that I feel the term has been cheapened. The popular
- window manager <ulink
- url="http://www.enlightenment.org">Enlightenment</ulink> has
- released <emphasis>nothing but</emphasis> development
- releases. Most often, the term is used to describe releases
- that are not even to alpha or beta stages though and if I
- were to release a pre-alpha release in order to keep interest
- in my project live, this is probably how I would have to label
- it.
- </para>
+ <para>Development release is much more vague term than
+ <quote>alpha</quote> or <quote>beta</quote>. I usually choose
+ to reserve the term for discussion of a development
+ branch. There are other ways to use the term. So many in fact,
+ that I feel the term has been cheapened. The popular window
+ manager <ulink
+ url="http://www.enlightenment.org">Enlightenment</ulink> has
+ released <emphasis>nothing but</emphasis> development
+ releases. Most often, the term is used to describe releases
+ that are not even to alpha or beta stages though and if I were
+ to release a pre-alpha release in order to keep interest in my
+ project live, this is probably how I would have to label
+ it.</para>
</listitem>
</varlistentry>
projects / fspm_howto / blobdiff