Contact information tells the users of your software how to start a conversation with the people responsible for the project.
This documentation element can be extremely short, and need not live on its own page. But it’s important to provide clear contact information to offer a path forward for the times when your users have questions that your written documentation doesn’t quite answer. Once the coding is done, one of the most important things you can do to help your project’s success is to establish a reputation that questions will be answered helpfully and promptly. (The other major thing being to provide a high-quality tutorial, of course!)
Example: Individual Email
If there is an individual who is the clear best contact point for the project, it is probably best to direct users to that person’s email address.
Getting in Touch
If you have questions or feedback, reach out to Peter K. G. Williams at pwilliams@cfa.harvard.edu.
If that person has a website, preferably with a distinct Contact page, a link to it provides redundancy.
In the modern internet, there’s no point to obscuring the email address with
[NOSPAM] and the like — the address is guaranteed to already be in spammers’
databases: if not from a public source, then from one of the data breaches that
happen across the commercial web every day. Make your users’ lives easier by
just giving them the real, actual email address.
The dual purpose of contact information
The primary purpose of this documentation element is to serve users who have questions — support. Your documentation can’t possible cover all questions that your users will have, so you want to make it as blazingly obvious how to get help when it’s needed. And the kind of help that people prefer above all others is help from a person.
An important additional purpose of this documentation element, however, is to make it clear who’s in charge — to identify leadership. This is especially relevant for scientific software where current or potential users might need to reach out with inquiries about formalizing collaborations, grant proposals, and so on. (Ironically, while the product of scientific research is ideally public and impersonal, its conduct is often very much the opposite.)
Although your contact information section will likely list one or more people’s names, it is not the purpose of this section to give credit for the creation of the software. This is better served by the author list associated with your project’s citation metadata. Therefore, your contact information should be minimal and focused on the above two needs; providing an extensive list of names will only muddle things.
For new projects, a single documentation element can meet both of these needs because the lists of relevant individuals are likely to be identical, or nearly so. But once a project reaches a sufficient scale, this element may need to bifurcate. If your project has acquired a robust user community, it has probably reached the point where your documentation should have a “Support” section, and you will be well-served to direct support questions to community forums rather than to project leadership. Meanwhile, for the reasons given above, it still remains important to provide a “Contact Information” section that identifies who’s in charge.
Example: Issue Tracker and Email
If your project’s source code is hosted on a platform like GitHub that comes with an associated issue tracker (e.g., GitHub Issues), you may wish to direct people there:
Contact Information
To report bugs, ask questions, or offer feedback, please file an issue on the project’s issue tracker on GitHub. This is the correct place to go even for general questions (i.e., things that aren’t bug reports).
For project-level inquiries, reach out to Peter K. G. Williams at pwilliams@cfa.harvard.edu.
This approach favors the “support” role of the contact information element. There are advantages to its impersonal nature: the guidance will remain valid even if the project leadership evolves over time, and interactions result in a public documentation trail. On the other hand, some users may not have existing accounts on your code-hosting platform (consider your personas), and even those that do may not feel comfortable using the issue tracker for generic support questions. If your issue tracker has a notion of “issue templates”, set up a few that make it clear that it’s appropriate to use the tracker for things other than bug reports.
Given an issue tracker link, savvy and/or determined users will be able to infer the identity of your project leadership. But why make things hard on people? If your primary contact mechanism is a public or depersonalized channel like an issue tracker, you’re encouraged to document a private contact channel as well. This is more equitable for people who don’t already know the project team personally.
Case Study: Bioconductor
For larger projects, the notion of “contact information“ starts becoming ill-defined. For instance, as of this writing, the Bioconductor homepage lists the following:
Connect With the Community
One way to think about the problem is that there are too many communications channels out there, all of which are potentially ways to contact someone about the project. The unfortunate thing is that you can’t control what communications channels your project needs to use. If people start posting questions about your project on StackExchange, it’s strongly in your interest to start monitoring and answering them there, even if you’d rather not add yet another discussion venue to the mix. Between that and the fact that “place for people to communicate with each other” is a kind of website that’s launched every day, popular projects should expect to constantly be shifting communications across different platforms, as a simple fact of life.
Another way to think about the issue is that there become too many different kinds of communication to support: user help, project news, leadership discussions, conduct issues, and more. When it comes to documentating project communication channels, it can be helpful to take this perspective and focus on users’ needs. These can be sorted into a few broad bins, such as:
- I have a question
- I want to get involved
- I want to know what’s new
- I want to talk to the people in charge
You can’t prevent people from using whichever communications channel they
stumble upon. The best you can do, then, is offer them clear guidance: “If you
have a question, go to the forum. If you want to get involved, introduce
yourself on the Zulip instance. If you want to know what’s new, follow our
Bluesky account. If you want to talk to leadership, send an email to xxx@yyy.”
People will still tweet support questions at the Bluesky account, but there’s
literally nothing you can do to prevent that.