Writing a company-wide developer's handbook

Question

I work for a small company. The software development arm of the company before I was hired consisted of one self-taught overworked guy. Now that I've been writing software for the company for a few years, I have been tasked with establishing formal company-wide software development practices. We currently have no guidelines, other than

Write code, test it, put it in a .zip file and send it to the client. Bonus points for TDD and version control.

My boss wants me to write a software developer's handbook which defines the general processes, protocols, tools, and guidelines we use to get things done. In other words, he wants a "This is what we do here" book to make it easier to get a new employee familiar with the way we do things, as well as to help my boss understand what his minions are doing and how they do it.

The way I see it, I'm laying a foundation and it needs to be done right. How would you go about choosing topics for such a handbook? Can you provide some example topics?

Side Note: If it matters, we are primarily a Microsoft .NET shop. And we are looking at agile practices such as XP and Scrum, but we may have to heavily modify them to make them work in our company.

Answer 1

I would break it down into sections like

• Current staff - names and titles (ideally with photos)
• Applications, logins to them, data to know and permission requests to have submitted
• Bookmarks to company sites and key external sites relevant to the business
• Applications that the company uses for comms, email, conference room booking, sharescreen
• Procedures for company related activities such as Expensing receipts, booking travel
• Developer Machine Setup. Describe the process of a setting up a new developers machine in detail. This is usually 'expected' to only take a day, but often it take 3-5 days in reality.
• The development process, how work is tracked, assigned and updated and what tools are used.
• How to test, what to test, when to test, where to test.
• Coding standards including file naming conventions and language specific standards.
• How to handle bugs, where to document them, how to go about fixing them.
• deployment process, what are the key things to know for production pushes.
• How to document, what to document, When to document.
• Where stuff 'is', e.g. location(s) for Code, Data, Standards, Documentation, Links and other assets.

Making it modular will also let you or others update pieces separately, for instance the employees names and positions will change frequently as people come and go.

For each section I'd try hard to write it from a 'newbie' point of view. Most important will be making sure it really makes sense to a newbie. Your boss obviously is not the right person to review this as he is not the intended audience. He's right to want it, just make sure the content doesn't end up being tested by him. Also a 'newbie' both only has "1 week" as being a newbie... and only has one point of view. So it's likely (and recommended) that the document will be refined with each new employee. In fact it's a pretty good task to also assign them for their first week, i.e. "Update the newbie manual".

For Agile/SCRUM:

The hardest part of doing Agile and SCRUM is 'really' doing it.

For reading I would start at http://agilemanifesto.org/ and go from there.

I would also read the well-known http://www.halfarsedagilemanifesto.org/ which adds weight to the fact that you really have to embrace all the aspects for it to work. If you have to heavily modify Agile for your organizations it's likely that people want the benefits - without using the correct processes. This fact itself should be presented to ward off any half-assyness.

Answer 2

It sounds like you're going to have to introduce some practices before you document them!

a) Source control - how do you store your sources and do revision control

b) Release management and tracking - how do you do a build, number a release, compare a current release candidate to a prior release

c) Problem management - how do you track bugs in your releases.

These are pretty basic things but they can take a lot of time (and possibly cost money) to implement.

Answer 3

Topics that I would include in a developer's handbook:

• Roles/positions within the department and their corresponding responsibilities
• Developer machine software requirements (i.e. required development environment)
• Where and how to access the source code repository
• Development tools being used (e.g. IDE)
• Coding style/standards
• Documentation standards
• Testing process
• Build process
• Deployment process
• Support and issue management process
• Where to get the most up-to-date version of this handbook

Keep in mind that this handbook should only contain items specific to development, and not company-wide information (which should be in an employee handbook).

Answer 4

Use of Source Control

• Which source control tool you are using.
• Syntax of common commands / tools in the IDE.
• Branching / merge strategy.
• What should the unit of a commit be? How long is too long to have a file checked out / not committed?
• What level of "doneness" does a commit / check-in denote? Compiles? Unit tests pass? Reviewed?
• What is expected to be included in the notes for a commit / check-in.
• Rollback procedures.