<HTML
><HEAD
><TITLE
>Maintaining a Project: Interacting with Users</TITLE
><META
NAME="GENERATOR"
CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="Free Software Project Management HOWTO"
HREF="index.html"><LINK
REL="PREVIOUS"
TITLE="Maintaining a Project: Interacting with Developers"
HREF="developers.html"><LINK
REL="NEXT"
TITLE="Bibliography"
HREF="b811.html"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#840084"
ALINK="#0000FF"
><DIV
CLASS="NAVHEADER"
><TABLE
SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TH
COLSPAN="3"
ALIGN="center"
>Free Software Project Management HOWTO</TH
></TR
><TR
><TD
WIDTH="10%"
ALIGN="left"
VALIGN="bottom"
><A
HREF="developers.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="80%"
ALIGN="center"
VALIGN="bottom"
></TD
><TD
WIDTH="10%"
ALIGN="right"
VALIGN="bottom"
><A
HREF="b811.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
></TABLE
><HR
ALIGN="LEFT"
WIDTH="100%"></DIV
><DIV
CLASS="SECT1"
><H1
CLASS="SECT1"
><A
NAME="USERS">4. Maintaining a Project: Interacting with Users</H1
><P
> If you've worked your way up to here, congratulations, you are
nearing the end of this document. This final section describes some
of the situations in which you, in your capacity as project
maintainer, will be interacting with users. It gives some
suggestions on how these situations might be handled effectively.
</P
><P
> Interacting with users is difficult. In our discussion of
interaction with developers, the underlying assumption is that in a
free software project, a project maintainer must constantly strive to
attract and keep developers who can easily leave at any time.
</P
><P
> Users in the free software community are different than developers
and are also different than users in the world of proprietary
software and they should be treated differently than either
group. Some ways in which the groups differ significantly follow:
</P
><P
> <P
></P
><UL
><LI
><P
>The lines between users and developers are blurred in ways
that is totally foreign to any proprietary development
model. Your users are often your developers and vice
versa.</P
></LI
><LI
><P
>In the free software world, you are often your users' only
choice. Because there is such an emphasis on not replicating the
work of others in the free software community and because the
element of competition present in the propriety software model is
absent (or at least in an extremely different form) in the free
software development model, you will probably be the only project
that does what you do (or at least the only one that does what
you do in the way that you do it). This means your responsiveness
to your users is even more important than in the proprietary
software world.</P
></LI
><LI
><P
>In an almost paradoxical situation, free software projects
have less immediate or dire consequences for ignoring their users
altogether. It is also often easier to do. Because you don't
usually need to compete with another product, chances are good
that you will not be scrambling to gain the features of your
competitor's newest program. This means that your development
process will have to be directed either internally, by a
commitment to your users, or through both.</P
></LI
></UL
>
</P
><P
> Trying to tackle this unique situation can only be done
indirectly. Developers and maintainers need to listen to users and
to try and be as responsive as possible. A solid knowledge of the
situation recounted above is any free software developer's best tool
for shifting his development or leadership style to fit the unique
process of free software project management. This chapters will try and
introduce some of the more difficult or important points in any
projects interactions with users and give some hints on how to
tackle these.
</P
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="TESTING">4.1. Testing and Testers</H2
><P
> In addition to your users being your developers, they are also
(and perhaps more commonly) your testers. Before I get flamed, I
should rephrase my sentence: <EM
>some of your
users</EM
> (those who explicitly volunteer) are your
testers.
</P
><P
> It is important that this distinction be made early on because not
all of your users want to be testers. Many users want to use
stable software and don't care if they don't have the newest,
greatest software with the latest, greatest features. These users
except a stable, tested piece of software without major or obvious
bugs and will be angry if they find themselves testing. This is
yet another way in which a split development model (as mentioned
in <A
HREF="developers.html#BRANCHES"
>Section 3.3</A
>) might come in handy.
</P
><P
> <SPAN
CLASS="QUOTE"
>"<A
HREF="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD"
TARGET="_top"
>Managing
Projects the Open Source Way</A
>"</SPAN
> describes what a
good test should look for:
</P
><P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Boundary conditions</DT
><DD
><P
>Maximum buffer lengths, data conversions, upper/lower
boundary limits, and so on.</P
></DD
><DT
>Inappropriate behavior</DT
><DD
><P
>Its a good idea to find out what a program will do if a
user hands it a value it isn't expecting, hits the wrong button,
etc. Ask yourself a bunch of <SPAN
CLASS="QUOTE"
>"what if"</SPAN
> questions
and think of anything that <EM
>might</EM
> fail or
<EM
>might</EM
> go wrong and find out what your
program would do in those cases.</P
></DD
><DT
>Graceful failure</DT
><DD
><P
>The answer to a number of the <SPAN
CLASS="QUOTE"
>"what if"</SPAN
>
questions above is probably <SPAN
CLASS="QUOTE"
>"failure"</SPAN
> which is
often the only answer. Now make sure that it happens
nicely. Make sure that when it crashes, there is some indication
of why it crashed or failed so that the user or developer
understands whats going on.</P
></DD
><DT
>Standards conformance</DT
><DD
><P
>If possible, make sure your programs conforms to
standards. If it's interactive, don't be too creative with
interfaces. If it is non-interactive, make sure it communicates
over appropriate and established channels with other programs
and with the rest of the system.</P
></DD
></DL
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN667">4.1.1. Automated testing</H3
><P
> For many programs, many common mistakes can be caught by
automated means. Automated tests tend to be pretty good at
catching errors that you've run into several times before or
the things you just forget. They are not very good at finding
errors, even major ones, that are totally unforeseen.
</P
><P
> CVS comes with a Bourne shell script called sanity.sh that is
worth looking at. Debian uses a program called lintian that
checks Debian packages for all of the most common errors. While
use of these scripts may not be helpful, there is a host of other
sanity checking software on the net that may be applicable (feel
free to email me any recommendations). None of these will create
a bug-free release but they will avoid at least some major
oversights. Finally, if your programs become a long term
endeavor, you will find that there are certain errors that you
tend to make over and over. Start a collection of scripts that
check for these errors to help keep them out of future releases.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN671">4.1.2. Testing by testers</H3
><P
> For any program that depends on user interactivity, many bugs
will only be uncovered through testing by users actually clicking
the keys and pressing the mouse buttons. For this you need
testers and as many as possible.
</P
><P
> The most difficult part of testing is finding testers. It's
usually a good tactic to post a message to a relevant mailing
list or news group announcing a specific proposed release date
and outlining the functionality of your program. If you put some
time into the announcement, you are sure to get a few responses.
</P
><P
> The second most difficult part of testing is
<EM
>keeping</EM
> your testers and keeping them
actively involved in the testing process. Fortunately, there are
some tried and true tactics that can applied toward this end:
</P
><P
> <P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>Make things simple for your testers</DT
><DD
><P
>Your testers are doing you a favor so make it as easy as
possible for them. This means that you should be careful to
package your software in a way that is easy to find, unpack,
install, and uninstall. This also means you should explain
what you are looking for to each tester and make the means for
reporting bugs simple and well established. The key is to
provide as much structure as possible to make your testers'
jobs easy and to maintain as much flexibility as possible for
those that want to do things a little differently.</P
></DD
><DT
>Be responsive to your testers</DT
><DD
><P
>When your testers submit bugs, respond to them and
respond quickly. Even if you are only responding to tell them
that the bug has already been fixed, quick and consistent
responses make them feel like their work is heard, important,
and appreciated.</P
></DD
><DT
>Thank your testers</DT
><DD
><P
>Thank them personally each time they send you
patch. Thank them publicly in the documentation and the about
section of your program. You appreciate your testers and your
program would not be possible without their help. Make sure
they know it. Publicly, pat them on the back to make sure the rest of
the world knows it too. It will be appreciated more than you
expected.</P
></DD
></DL
></DIV
>
</P
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="SUPPORT">4.2. Setting up Support Infrastructure</H2
><P
> While testing is important, the large part of your interactions
and responsibility to your users falls under the category of
support. The best way to make sure your users are adequately
supported in using your program is to set up a good infrastructure
for this purpose so that your developers and users help each other
and less of the burden falls on you. This way, people will also
get quicker and better responses to their questions. This
infrastructure comes in several major forms:
</P
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN694">4.2.1. Documentation</H3
><P
> It should not come as any surprise that the key element to any
support infrastructure is good documentation. This topic was
largely covered in <A
HREF="starting.html#DOCUMENTATION"
>Section 2.5</A
> and will not be
repeated here.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="MAILINGLISTS">4.2.2. Mailing lists</H3
><P
> Aside from documentation, effective mailing lists will be your
greatest tool in providing user support. Running a mailing list
well is more complicated than installing mailing list software
onto a machine.
</P
><DIV
CLASS="SECT4"
><H4
CLASS="SECT4"
><A
NAME="AEN701">4.2.2.1. Separate lists</H4
><P
> A good idea is too separate your user and development mailing
lists (perhaps into project-user@host and project-devel@host)
and enforce the division. If people post a development question
onto -user, politely ask them to repost it onto -devel and vise
versa. Subscribe yourself to both groups and encourage all
primarily developers to do the same.
</P
><P
> This system provides so that no one person is stuck doing all of
the support work and works so that users learn more about the
program, they can help newer users with their questions.
</P
></DIV
><DIV
CLASS="SECT4"
><H4
CLASS="SECT4"
><A
NAME="AEN705">4.2.2.2. Choose mailing list software well</H4
><P
> Please don't make the selection of mailing list software
impulsively. Please consider easy accessibility by users without
a lot of technical experience so you want to be as easy as
possible. Web accessibility to an archive of the list is also
important.
</P
><P
> The two biggest free software mailing list programs are <A
HREF="http://www.greatcircle.com/majordomo/"
TARGET="_top"
>majordomo</A
>
and <A
HREF="http://www.list.org/"
TARGET="_top"
>GNU Mailman</A
>. A
long time advocate of majordomo, I would now recommend any
project choose GNU Mailman. It fulfills the criteria listed
above and makes it easier. It provides a good mailing
list program for a free software project maintainer as opposed
to a good mailing list application for a mailing list
administrator.
</P
><P
> There are other things you want to take into consideration in
setting up your list. If it is possible to gate your mailing
lists to Usenet and provide it in digest form as well as
making them accessible on the web, you will please some users
and work to make the support infrastructure slightly more
accessible.
</P
></DIV
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN712">4.2.3. Other support ideas</H3
><P
> A mailing list and accessible documentation are far from all you
can do to set up good user support infrastructure. Be
creative. If you stumble across something that works well, email me
and I'll include it here.
</P
><DIV
CLASS="SECT4"
><H4
CLASS="SECT4"
><A
NAME="AEN715">4.2.3.1. Make your self accessible</H4
><P
> You can not list too few methods to reach you. If you hang out
in an <SPAN
CLASS="ACRONYM"
>IRC</SPAN
> channel, don't hesitate to list it
in your projects documentation. List email and snailmail
addresses, and ways to reach you via <SPAN
CLASS="ACRONYM"
>ICQ</SPAN
>,
<SPAN
CLASS="ACRONYM"
>AIM</SPAN
>, or Jabber if they apply.
</P
></DIV
><DIV
CLASS="SECT4"
><H4
CLASS="SECT4"
><A
NAME="AEN721">4.2.3.2. Bug management software</H4
><P
> For many large software projects, use of bug management software
is essential to keep track of which bugs have been fixed, which
bugs have not been fixed, and which bugs are being fixed by
which people. Debian uses the <A
HREF="http://bugs.debian.org"
TARGET="_top"
>Debian Bug Tracking System</A
>
(<SPAN
CLASS="ACRONYM"
>BTS</SPAN
>) although it may not be best choice for
every project (it seems to currently be buckling under its own
weight) As well as a damn good web browser, the Mozilla project
has spawned a sub-project resulting in a bug tracking system
called <A
HREF="http://www.mozilla.org/projects/bugzilla/"
TARGET="_top"
>bugzilla</A
>
which has become extremely possible and which I like a lot.
</P
><P
> These systems (and others like them) can be unwieldy so
developers should be careful to not spend more time on the bug
tracking system than on the bugs or the projects themselves. If
a project continues to grow, use of a bug tracking system can
provide an easy standard avenue for users and testers to report
bugs and for developers and maintainers to fix them and track
them in an orderly fashion.
</P
></DIV
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="RELEASING">4.3. Releasing Your Program</H2
><P
> As mentioned earlier in the HOWTO, the first rule of releasing is,
<EM
>release something useful.</EM
> Non-working or
not-useful software will not attract anyone to your
project. People will be turned off of your project and will be likely
to simply gloss over it next time they see a new version
announced. Half-working software, if useful, will intrigue people,
whet their appetites for versions to come, and encourage them to
join the development process.
</P
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN732">4.3.1. When to release</H3
><P
> Making the decision to release your software for the first time
is an incredibly important and incredibly stressful decision. But
it needs to done. My advice is to try and make something that
is complete enough to be usable and incomplete enough to allow
for flexibility and room for imagination by your future
developers. It's not an easy decision. Ask for help on a local
Linux User Group mailing list or from a group of developer
friends.
</P
><P
> One tactic is to first do an <SPAN
CLASS="QUOTE"
>"alpha"</SPAN
> or
<SPAN
CLASS="QUOTE"
>"beta"</SPAN
> release as described below in <A
HREF="users.html#ALPHABETA"
>Section 4.3.3</A
>. However, most of the guidelines described
above still apply.
</P
><P
> <EM
>When you feel in your gut that it is time and you feel
you've weighed the situation well several times, cross your
fingers and take the plunge.</EM
>
</P
><P
> After you've released for the first time, knowing when to release
becomes less stressful, but just as difficult to gauge. I like
the criteria offered by Robert Krawitz in his article, <A
HREF="http://www.advogato.org/article/196.html"
TARGET="_top"
><SPAN
CLASS="QUOTE"
>"Free
Software Project Management"</SPAN
></A
> for maintaining a
good release cycle. He recommends that you ask yourself,
<SPAN
CLASS="QUOTE"
>"does this release..."</SPAN
>
</P
><P
> <P
></P
><UL
><LI
><P
>Contain sufficient new functionality or bug fixes to be
worth the effort.</P
></LI
><LI
><P
>Be spaced sufficiently far apart to allow the user time
to work with the latest release.</P
></LI
><LI
><P
>Be sufficiently functional so that the user can get work
done (quality).</P
></LI
></UL
>
</P
><P
> If the answer is yes to all of these questions, its probably time
for a release. If in doubt, remember that asking for advice can't
hurt.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN754">4.3.2. How to release</H3
><P
> If you've followed the guidelines described in this HOWTO up
until this point, the mechanics of doing a release are going to
be the easy part of releasing. If you have set up consistent
distribution locations and the other infrastructure described in
the preceding sections, releasing should be as simple as building
the package, checking it once over, and uploading it into the
appropriate place and then making your website reflect the
change.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="ALPHABETA">4.3.3. Alpha, beta, and development releases</H3
><P
> When contemplating releases, it worth considering the fact that
not every release needs to be a full numbered release. Software
users are accustomed to pre-releases but you must be careful to
label these releases accurately or they will cause more problems then
they are worth.
</P
><P
> The observation is often made that many free software developers
seem to be confused about the release cycle. <SPAN
CLASS="QUOTE"
>"<A
HREF="http://news.linuxprogramming.com/news_story.php3?ltsn=2000-10-31-001-05-CD"
TARGET="_top"
>Managing
Projects the Open Source Way</A
>"</SPAN
> suggests that you memorize
the phrase, <SPAN
CLASS="QUOTE"
>"Alpha is not Beta. Beta is not Release"</SPAN
>
and I'd agree that tis is a probably a good idea.
</P
><P
> <P
></P
><DIV
CLASS="VARIABLELIST"
><DL
><DT
>alpha releases</DT
><DD
><P
>Alpha software is feature-complete but sometimes only
partially functional.</P
><P
>Alpha releases are expected to be unstable, perhaps a
little unsafe, but definitely usable. They
<EM
>can</EM
> have known bugs and kinks that have
yet to be worked out. Before releasing an alpha, be sure to
keep in mind that <EM
>alpha releases are still
releases</EM
> 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.</P
></DD
><DT
>beta releases</DT
><DD
><P
>Beta software is feature-complete and functional, but is
in the testing cycle and still has a few bugs left to be
ironed out.</P
><P
>Beta releases are general expected to be usable and
slightly unstable, although definitely <EM
>not
unsafe.</EM
> 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 to be in the very near future and can
help keep interest by giving people
<EM
>something.</EM
></P
></DD
><DT
>development releases</DT
><DD
><P
><SPAN
CLASS="QUOTE"
>"Development release"</SPAN
> is much a more vague
term than <SPAN
CLASS="QUOTE"
>"alpha"</SPAN
> or <SPAN
CLASS="QUOTE"
>"beta"</SPAN
>. I
usually choose to reserve the term for discussion of a
development branch although there are other ways to use the
term. So many in fact, that I feel the term has been
cheapened. The popular window manager <A
HREF="http://www.enlightenment.org"
TARGET="_top"
>Enlightenment</A
> has
released <EM
>nothing but</EM
> development
releases. Most often, the term is used to describe releases
that are not even alpha or beta and if I were to release a
pre-alpha version of a piece of software in order to keep
interest in my project alive, this is probably how I would
have to label it.</P
></DD
></DL
></DIV
>
</P
></DIV
></DIV
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
NAME="ANNOUNCING">4.4. Announcing Your Project</H2
><P
> Well, you've done it. You've (at least for the purposes of this
HOWTO) designed, built, and released your free software
project. All that is left is for you to tell the world so they
know to come and try it out and hopefully jump on board with
development. If everything is in order as described above, this
will be a quick and painless process. A quick announcement is all
that it takes to put yourself on the free software community's
radar screen.
</P
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN792">4.4.1. Mailing lists and Usenet</H3
><P
>Announce your software on Usenet's <A
HREF="news:comp.os.linux.announce"
TARGET="_top"
>comp.os.linux.announce</A
>. If
you only announce your software in two places, have it be c.o.l.a
and freshmeat.</P
><P
> However, email is still the way that most people on the Internet
get their information. Its a good idea to send a message
announcing your program to any relevant mailing list you know of
and any other relevant Usenet discussion groups.</P
><P
>Karl Fogel recommends that use you simple subject
describing the fact that the message is an announcement, the name
of the program, the version, and a half-line long description of
its functionality. This way, any interested user or developer
will be immediately attracted to your announcement. Fogel's
example looks like:
</P
><TABLE
BORDER="1"
BGCOLOR="#E0E0E0"
WIDTH="100%"
><TR
><TD
><FONT
COLOR="#000000"
><PRE
CLASS="SCREEN"
>Subject: ANN: aub 1.0, a program to assemble Usenet binaries</PRE
></FONT
></TD
></TR
></TABLE
><P
> The rest of the email should describe the programs functionality
quickly and concisely in no more than two paragraphs and should
provide links to the projects webpage and direct links to
downloads for those that want to try it right away. This form
will work for both Usenet and mailing list posts.
</P
><P
> You should repeat this announcement process consistently in the
same locations for each subsequent release.
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN801">4.4.2. freshmeat.net</H3
><P
> Mentioned earlier in <A
HREF="starting.html#EVALWHERE"
>Section 2.1.2.1</A
>, in today's free
software community, announcements of your project on freshmeat
are almost more important than announcements on mailing lists.
</P
><P
> Visit the <A
HREF="http://freshmeat.net"
TARGET="_top"
>freshmeat.net
website</A
> or their <A
HREF="http://freshmeat.net/add-project/"
TARGET="_top"
>submit project
page</A
> to post your project onto their site and into their
database. In addition to a large website, freshmeat provides a
daily newsletter that highlights all the days releases and
reaches a huge audience (I personally skim it every night for any
interesting new releases).
</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
NAME="AEN808">4.4.3. Project Mailing List</H3
><P
>If you've gone ahead and created mailing lists for your
project, you should always announce new versions on these
lists. I've found that for many projects, users request a very
low-volume announce only mailing list to be notified when new
versions are released. freshmeat.net now allows users to subscribe
to a particular project so they receive emails every time a new
version is announced through their system. It's free and it can
stand in for an announce-only mailing list. In my opinion, it
can't hurt.</P
></DIV
></DIV
></DIV
><DIV
CLASS="NAVFOOTER"
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
CELLSPACING="0"
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
><A
HREF="developers.html"
ACCESSKEY="P"
>Prev</A
></TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
><A
HREF="index.html"
ACCESSKEY="H"
>Home</A
></TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
><A
HREF="b811.html"
ACCESSKEY="N"
>Next</A
></TD
></TR
><TR
><TD
WIDTH="33%"
ALIGN="left"
VALIGN="top"
>Maintaining a Project: Interacting with Developers</TD
><TD
WIDTH="34%"
ALIGN="center"
VALIGN="top"
> </TD
><TD
WIDTH="33%"
ALIGN="right"
VALIGN="top"
>Bibliography</TD
></TR
></TABLE
></DIV
></BODY
></HTML
>
