What amount of documentation is needed for a non-trivial one-man software project

Question

I have been writing software for about 2 years and am now in charge of determining what documentation is to be produced for software projects in my department due to being the only developer at the company.

I do not have any project management, design, or requirements gathering experience but am keen to do a good job my first time round.

At my previous company (a consulting firm), it was up to the client as to how much documentation they wanted/needed (with a little guidance from us, of course.) We had documentation templates for pretty much everything! Obviously, as a one-man team, I wouldn't need all of that. So, what would be an acceptable level of documentation in my current case? I'm thinking along the lines of: a scope document, a requirements document, a project plan, etc.

Answer 1

You might start with answering the three basic questions:

• What: What are you going to do? Describe what your project will do to satisfy the customer requirements. This is a requirements document.
• How: How are you going to do it? Describe to the level you feel is appropriate. This is a design document.
• When: When are you going to do it by? Describe your overall plan down to a level you're comfortable with. This is the project plan.

The other two basic questions, who and why, are either trivial (it's just you!) or too philosophical ("so my kids can eat").

Answer 2

Personally I thinkt he only things that are essential are:

• Requirements if it's an external client;
• Functional specification; and
• A wiki for any technical design or architecture that can't be gleamed from the code (easily).

Everything else is just writing documents for process sake that no one will ever read (although the likelihood of the above ever getting read isn't that great either).

Answer 3

Hi Andrew

At a bare minimum you're going to need three documents:

• A Vision/Scope/Requirements document (these can be rolled into one), includes the stakeholders necessary signoffs.
• A Test plan, including test scripts that you'll going to use internally and also as part of your acceptance tests
• A Support Handover document, which describes your app's general architecture, list down the servers that are involved (including accesses/passwords) and troubleshooting tips.

A project plan is nice to have but usually only needed when you're coordinating the development effort with other people. When there is only one person involved, you're only going to need to show when are you going to start acceptance tests and perform fixes after the tests, which I suppose can be incorporated as part of the Scope document..

I hope this helps.

thanks.

Answer 4

You need to determine who your audience is before writing the documentation. Is it for management, operations, the person who's going to replace you, a junior developer, auditors, etc..

For one company, I needed to document what to do if they have problems while I was on vacation. My documentation was:

If anything stops working, first try rebooting your PC, and if the problem persists reboot the server.

Answer 5

As an alternative to documentation intended to describe the application design, ie. how it works, I would recommend writing unit tests. This may not seem obvious at first, but I have found this has helped me out in describing code I myself wrote a while ago, but did not want the overhead of formal written documentation.

The unit tests themselves provide good examples of how the code is to be used, and if you have written decent tests, can show subtleties in the usage that may be awkward to describe in written documentation.

You say you are working in a one man situation, therefore unit tests are an even better fit as they are executable code themselves and are kept right alongside your application code in a version control system.

If you leave the job, unit tests are going to be more valuable to your replacement than written documentation because they can actually see the code running and get a better feel for how it can be used.

Unit tests are just code that test other code, so there is also a better chance (than written documentation) that they will be kept up to date by developers as time advances.

Answer 6

Different projects require different amounts of and kinds of documentation, but I've seen a few best practices succeed on a wide variety of teams and projects:

• wherever possible, make your app self-documenting. For example: clarify error message text (including how to fix the problem, if appropriate/known), use self-describing configuration file formats (with comments), add help text in command-line tools, and provide in-code API documentation (e.g. javadoc), include unit tests with your code, etc. Self-documenting code dramatically reduces external documentation needs.

• if you write documentation outside your code, check it in with your code! Documentation has a habit of getting lost or ignored if it doesn't live very close to your sources.

• most documentation is never read after the project is over, so prioritize your time documenting like you prioritize your time coding. Try to only write top-priority documentation that someone is likely to actually read.

• Documentation before software is written is all about getting buy-in and feedback from others in your company. I like to write a quick, high-level functional spec with a prioritized list of requirements, a (short!) explanation of the project's goals and target users, and ideally some UI wireframes (or API definitions, URL formats, etc. for UI-less projects). The primary goal of pre-coding documentation is to get agreement and feedback from others about what's gonna get built, so don't go overboard on details-- write only enough to get everyone on the same page. Some methodologies eschew this step completely and just build a functional prototype, which works well in some projects. Keep in mind the point here is enhancing communication and consensus, nothing more.

• Documentation after code is written is primarily for non-developers (QA engineers, support/operations people, technical writers, etc.) who have to support your code. Per above, the more your code is self-documenting, the less you have to do here.

• It's usually useful to have a very short architectural overview for future developers fixing bugs in or maintaining your code. Keep it very short-- flowcharts or bullet points are fine, since devs will just go read your code for the details. And check it in with your code!!!!

• if you have operations or support people who will support your code, document how to install your software, how to configure it, how to operate it (e.g. command line tools), and how to detect & fix problems. If you don't do this, you will become the support person and you don't want that.

• wikis work well for capturing "tribal knowledge" about an app and can shift the support burden from you to your app's support people. If anyone can figure out how to get a wiki to automatically check changes into source control, let me know! :-)

• focus documentation effort on your code's interactions with the outside world: expected UI behavior, APIs, URL & parameter formats, command-line switches, etc. Documenting behavior internal to your code is a lower priority-- since generally only developers care about it, and they can read your code to find out!

• it's usually best to produce a small amount of high-quality, high-level documentation (overview of features, architecture, requirements, API, etc.) rather than voluminous specs detailing every possible thing.

Answer 7

You need to consider the long term and/or bigger picture. You're the only developer today, but what happens if you hire more developers to work on your project(s) a year from now? What if you decide to leave for another opportunity, and the company needs to replace you sometime down the road?

For each project you should at a minimum produce a requirements document, and a reasonable amount of design documentation and specifications for functional behavior. A decent set of use cases are always a nice thing to have, because in addition to helping you think about the requirements and eventual implementation yourself, they're also very useful to a much wider audience that includes people less technically-inclined than yourself. Ideally you should also produce a project plan/schedule of some sort, with milestones and deliverables delineated, for your own benefit and for the benefit of any other stakeholders in the project. The amount (and possibly types) of documentation you should produce will probably vary based on the type and scope of each project -- since you are the only developer I assume that most of the projects in your department will be of limited scope, and won't require the same level of documentation as more extensive projects involving larger teams of people. All the same, producing the appropriate documentation for your project(s) will probably serve to help clarify things in your own mind, provide one mechanism for soliciting discussion/feedback from your stakeholders, and providing information for posterity if that should become necessary.