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.

  • 3
    Your current process is very poor. Do you have company support to change your current process, it will not come cheap, the type of change that is required will take money. There are lots of books on the subject, most of those pracices have tools, which are required to implement in them in a way that doesn't require a great deal of effort.
    – Ramhound
    May 2, 2012 at 12:30
  • shopping for handbook topics?
    – gnat
    May 2, 2012 at 15:03
  • 1
    @gnat Good point. See edit.
    – Phil
    May 2, 2012 at 15:30
  • good edit (you apparently followed the link). I'd also change What kinds of topics do you think are important... to something like How would you gauge the importance of the topics... - that way, it would be more inline with Jeff's guidance as far as I understand it
    – gnat
    May 2, 2012 at 15:35
  • 1
    I'm not really concerned about how to gauge the importance of the topics, as I think I can already do that. Rather, I'm looking for examples. I've always considered answers to abstract questions to be better when accompanied with examples. See edit. BTW, I appreciate your help making my question better.
    – Phil
    May 2, 2012 at 15:48

4 Answers 4


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.

  • 7
    I like how frequently you're editing this. How... agile of you. :)
    – Phil
    May 1, 2012 at 20:21
  • We're not necessarily wanting to modify agile principles in general. We would just modify specific practices such as XP, as we don't really have the manpower to implement all the required roles. That may be another question for another day.
    – Phil
    May 1, 2012 at 20:27
  • Sorry, I removed the answer for now because the question has been modified.
    – Phil
    May 2, 2012 at 15:31
  • 1
    Bonus points if you set up a company wiki to hold this info... May 2, 2012 at 19:14
  • Hi Spencer, that's interesting. I also just started using a github wiki with markdown. Any thoughts on how they compare. Obviously many folks know github from code and markdown from SO, so it's easy to get adopted. May 4, 2012 at 14:19

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.

  • 2
    +1 for keeping it simple and concentrating on important issues. We really don't need "big government" mandates on coding styles. May 2, 2012 at 0:06

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).


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.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.