|
Unix Programming - Best Practices for Working with Open-Source Developers - Good Communication Practice
Good Communication Practice
Your software and documentation won't do the world much good if
nobody but you knows they exist. Also, developing a visible presence for
the project on the Internet will assist you in recruiting users and
co-developers. Here are the standard ways to do that.
Announce to Freshmeat.
Besides being widely read itself, this group is a major feeder for
Web-based technical news channels.
Never assume the audience has been reading your release
announcements since the beginning of time. Always include at least a
one-line description of what the software does. Bad example:
“Announcing the latest release of FooEditor, now with themes
and ten times faster”. Good example: “Announcing the
latest release of FooEditor, the scriptable editor for touch-typists,
now with themes and ten times faster”.
Announce to a relevant topic newsgroup.
Find a Usenet topic group directly relevant to your application,
and announce there as well. Post only where the
function
of the code is relevant, and exercise
restraint.
If (for example) you are releasing a program written in Perl
that queries IMAP servers, you should certainly post to comp.mail.imap. But you should probably
not post to comp.lang.perl
unless the program is also an instructive example of cutting-edge Perl
techniques.
Your announcement should include the URL of a project website.
If you intend trying to build any substantial user or developer community
around your project, it should have a website. Standard things to have
on the website include:
-
The project charter (why it exists, who the audience is, etc.).
-
Download links for the project sources.
-
Instructions on how to join the project mailing list(s).
-
A FAQ (Frequently Asked Questions) list.
-
HTMLized versions of the project documentation.
-
Links to related and/or competing projects.
Refer to the website examples in Chapter16 for examples of what a well-educated project
website looks like.
An easy way to have a website is to put your project on one of
the sites that specializes in providing free hosting. In 2003
the two most important of these are SourceForge (which is a
demonstration and test site for proprietary collaboration tools) or
Savannah (which hosts open-source projects as an ideological
statement).
Host project mailing lists.
It's standard practice to have a private development list
through which project collaborators can communicate and exchange
patches. You may also want to have an announcements list for people
who want to be kept informed of the project's progress.
If you are running a project named ‘foo’, your
developer list might be <foo-dev> or
<foo-friends>; your announcement list might be
<foo-announce>.
An important decision is just how private the
“private” development list is. Wider participation in
design discussions is often a good thing, but if the list is
relatively open, sooner or later you
will
get
people asking new-user questions on it. Opinions vary on how best to
solve this problem. Just having the documentation tell the new users
not to ask elementary questions on the development list is not a
solution; such a request must be enforced somehow.
An announcements list needs to be tightly controlled. Traffic should be
at most a few messages a month; the whole purpose of such a list is to
accommodate people who want to know when something important happens, but
don't want to hear about day-to-day details. Most such people will
quickly unsubscribe if the list starts generating significant clutter in
their mailboxes.
Release to major archives.
See the section Where Should I Look? in
Chapter16 for specifics on
the major open-source archive sites. You should release your package
to these.
Other important locations include:
-
The Python Software Activity
site (for software written in Python).
-
The CPAN, the
Comprehensive Perl Archive Network (for software written in Perl).
[an error occurred while processing this directive]
|
