Documentation that developers need to do their jobs

A fellow technical writer asked me this week about the documentation that developers need to do their jobs. He was thinking not of the guides people need when they want to integrate their systems with another organisation’s systems, but rather the internal guides developers may write for themselves about their projects and tools.

That’s a very good question. I’ve thought about it over the last couple of days, and pulled together a list of the types of developer-focused documentation I’ve come across. If you have any to add, please do!

The list is confined to documents relating to the role of software engineer/developer. It doesn’t include more general information that all employees need, such as human resources and facilities.

Information about the project and system they’re working on

• Who the people are: engineering team members, product managers, technical writers, stakeholders.
• Customers: Who they are and what they do, or would like to do, with the system or application that the team is developing.
• Goals: Mission, vision, goals for the upcoming month/quarter/year.
• Product requirements document for the system, application, or major feature that they’re working on.
• Design documents.
• Architectural overview, preferably in the form of a diagram.
• Comments in the code, written by their fellow developers.

Help with their development environment

• How to set  up the development environment for the application/system that the team is developing.
• Guides to specific tools, whether built in-house or third party, including the IDE of choice, build tool, source repository.
• A pointer to the issue tracker used by the team.
• Guide to the team’s code review tool and procedures.
• Best practices for writing automated tests, and information about existing code coverage.
• Links to the team’s online chat room, useful email groups, and other communication tools used by the team.
• Where to go with technical and tooling problems.

Coding guides

• Coding style guides for each programming language in use.
• Guidelines for in-code comments: style; where to put them; how long they should be; the difference between simple comments and those that are intended for automated doc generation such as Javadoc; and encouragement that comments in the code are a Good Thing.
• Best practices for code readability.

Sundry useful guides

• Communication guidelines, if the developer’s role will involve significant liaison with third-party developers, customers, or important stakeholders.
• A map to the nearest coffee machine, preferably reinforced by a path of glowing floor lights.

Too much information can be a bad thing. 🙂 I spotted this sign on a recent trip to Arizona: