Magazine article Computers in Libraries

How to Document Your Software: My Goal Here Is a Basic Template to Use for Documenting Software When You Want You Want to Package It for Sharing

Magazine article Computers in Libraries

How to Document Your Software: My Goal Here Is a Basic Template to Use for Documenting Software When You Want You Want to Package It for Sharing

Article excerpt

Last night I tried to install some software, but it didn't work. The process was painful because the software's installation documentation left a lot to be desired. I wasn't sure which order I should use to perform certain steps. Some of the steps assumed I knew things I could only guess at. Many steps were implied, instead of being explicitly spelled out in detail. The documentation provided never made it clear how to know when the installation was complete and working properly. The result was failure. I still haven't gotten it working at all.

Does this sound familiar?

Let's talk about how to write good documentation. My goal here is a basic template to use for documenting software when you want to package it for sharing. If you're more of the consumer-of-software type, you can use the following descriptions as a baseline of what to look for when you're installing somebody else's software. If a package you download to install and review has the following things, you might have a good chance of getting it running; if it doesn't, you should be wary and prepare yourself for an adventure.

If you're not the software-sharing or software-installing type, you can use this document as a guide to what you should expect your peers to be able to compose or consume. Preparing documentation like this isn't a trivial task--it's a critical step in sharing. Creating and maintaining installation documentation is time-consuming; it requires precision and clarity. It should be budgeted for and scheduled as a major part of the process from the outset of any software project.

The Basics--What to Aim For

Software should, at a minimum, come with three text files (each preferably a plain text file, because that's the easiest thing to review and maintain). Each file should explain one thing:

1. README: What is this software and what's it for?

2. LICENSE: What are your terms if I want to use, copy, modify, or redistribute it?

3. INSTALL: How exactly do I install it?

The README file can be a simple line or two explaining what your software does, if it's simple software. For example, "Acommandline application that converts files from format Ainto format B." "A web application written using language Foo and web framework Bar that allows users to edit metadata in format Baz." If your software is more complex than that, tell us about it. What are the key pieces? How do they fit together? Is there some background reading potential users of your software should do so they can be prepared to use it properly? Who are you and how should people get in touch with you with questions and comments? Keep it concise, but these topics are all fair game because anybody would be glad to see this kind of information in a README file.

The LICENSE file should explain who wrote the software and what rights are given to users. Even if it's a free/libre/open source software package or it's proprietary, if it's your software, you should disclose your authorship and determine and communicate the rights you wish to assign to other users before you distribute it.

The INSTALL file can take various forms. If it's a standard command-line or server application that builds with a makefile, the standard, generic installation instructions for "configure; make; make install" might be perfect. (In case you don't know what that means, a lot of system-level software packages are built using common configuration and compilation techniques. They can all be configured and compiled with the exact same instructions, which is something we could all aspire to!) If it's a one-line script, you can demonstrate common usage patterns with the options and arguments it accepts. If it's a complicated application with multiple pieces that must be configured separately and connected correctly, though, you have more work ahead of you. I'll focus on this case from here on out.

Installation Details--What to Do, Precisely

Let's assume we have a web application we want to share with other people. …

Search by... Author
Show... All Results Primary Sources Peer-reviewed

Oops!

An unknown error has occurred. Please click the button below to reload the page. If the problem persists, please try again in a little while.