The team I currently am part of experiences fairly high turnover, with members typically moving to different projects within the same company. Currently our "training" for new members is to pair them with a primary contact (usually the most recent person to complete their training) who will provide them with hands-on experience and will ask more senior developers if the newer hire ask something the mentor doesn't know. It provides a chance for the new hire to get involved quickly, and challenges the mentor to improve his/her understanding of the system also.

However, as you can imagine, this style of training is very time consuming, and doesn't provide a very good knowledge transfer (misconceptions propagate, gaps expand).

I've been tasked with generating documentation and training materials for our future new hires. I already do technical writing occasionally, but it's for the end user and is highly specific with lots of screenshots and consumes a large amount of time to complete.

Creating the new documentation for new hires is considered low priority and I've only currently got ~40 hours to work on it. Documenting the system the current way I write technical documentation would barely scratch the surface in 40 hours. Especially considering I have to document not only about the code base, but also about deployments and support.

How can I quickly write documentation to get new hires up to date as quickly as possible without investing significant time in writing the documentation?

Additional Information:
We currently have both a wiki, and some training documentation, however both are kind of sparse.

  • 2
    How is this about software development? Sounds like you need a teaching consultant, not a programmer.
    – Cyclops
    Commented Jan 10, 2012 at 19:15
  • 4
    If documentation is not part of software development, are comments not part of source code?
    – Malfist
    Commented Jan 10, 2012 at 19:25
  • Writing text that explains how the code works, is certainly part of software development. "Generating documentation and training materials for new hires" - is not part of software development, and a programmer's skillset would be unlikely to be appropriate. Nor is the problem of training new hires, specific to programming - your question is entirely generic.
    – Cyclops
    Commented Jan 10, 2012 at 23:08

5 Answers 5


Good question. Programmer on-the-job training is very rarely taken seriously, nor is it talked about often.

Some ideas I've seen work well:

  • In your wiki, have a new-hire rampup document (the one you're writing). In that document, describe teh tasks that the new hire will perform for the first 1-2 weeks. Where I work, there's loads to know from the get-go, from internal software/tools, to processes, to locations of specific types of information. edit> we have instructions like "install x, y, z in order" with screenshots for configuration etc. So configuring a system or farm (VMs) with Win Server, SQL Server, SharePoint, BizTalk, our software is not as simple as it sounds. This goes for the other versions of those applications that we support.
  • Practice problems. Where I am, we have a product that exposes a large-ish API. So it's always beneficial for us to go through our own products documentation for writing (pre-determined) extensions just as our clients/customers would. So if you had a math library as part of your product's API, have a practice problem that is "write a calculator using our API" or something like that.
  • Mentors are good. Keep them. We do that here too, and not only is it a good way to meet people/make friends, but they're invaluable as a source of learning. I recommend not having it be the most recent person to finish the training as they don't have the corporate knowledge history that someone else might. Have everyone do it on a rotation.
  • We do (roughly) weekly presentations/tech talks. Have the new hires pick something from your product (or assign it) and do a presentation after their 3rd week. Make sure they know that there is room for them to be wrong, and the team can correct them if they bugger anything up in the presentation.
  • Have the new hires work on documentation when they start. It forces them to read it.

As Dan McGrath notes, it's a good idea to encourage new hires to improve the wiki for them as well.

  • 2
    +1. It (imho) would be good to add that the new hire should also improve the wiki/documentation as they come across something this is missing or deficient. This helps your coming improving your onboarding resources while minimizing the time spent by your most experienced staff. I find it also helps solidify the new hires understanding. Commented Jan 10, 2012 at 23:09
  • All good points and things we do at work, apart from the last one about getting new hires to work on documentation. A couple of problems with that: a) It's a bit too menial. b) Probably contains product jargon. c) How will they know whether it is correct if they are new?
    – Burhan Ali
    Commented Apr 29, 2012 at 22:12

First, I would suggest that you don't have to make your new hire training doc as thorough as something you'd write for a client. It needs to be technical enough for a new dev to be able to use as a guide, but not so detailed that it outlines every small thing. They will be able to talk with the team if they have questions after all.

What are the top 10 things a new hire needs to know to be useful to your team? Concentrate on these things. Make them your hit list of items so that a new dev will have enough to do, and enough information to keep them going. If you have too many things on the list ask yourself if they will be doing it in their first two or three weeks. If they won't be doing something in this time, then perhaps it shouldn't be in the on boarding guide.

For each section of your guide, make sure there is a go-to person highlighted right at the top. This way, if the new hire has any questions they know who to go to for help. Also, make sure that one team member isn't the go-to person for too many sections. You don't want to take one person's time up with new hire questions if they are not the mentor.

Don't spend your full week on this document. Leave yourself some time to adjust it after you let at least one new hire go through it. See what works well, what doesn't, and fix.

  • The ~40 comes from me finishing other projects early, so once I exhaust the first 40 hours, it doesn't mean I won't have more time later.
    – Malfist
    Commented Jan 10, 2012 at 19:24
  • 1
    @Malfist - Fair enough. But, if you don't have time, and this is a low priority, banging out a first draft to test run while you work on your projects might be best. Take the iterative approach to this so that it does get worked on and you get more feedback. If you pick your 10 things, and a new hire says 'actually, section 4 I didn't really use, but a section on ____ would have been nice' you know how to improve and update the doc to be more useful to the next person.
    – Tyanna
    Commented Jan 10, 2012 at 19:46

I have recently started on a similar document at my place of work, with similar time constraints. I empathize that it is easy to want to write it at a very detailed level, as I did at first too, but that might actually be counter-productive.

If someone new is starting in a role, they are likely inundated with information for the first several weeks. Having their initial training be a brain dump of a developer who's been at a company for a number of years, will in my mind far over complicate what someone needs to know for their first few months or even year in that position. Keep it high level, try to use standard jargon and concepts, and then expand on them with the specifics from within the company's processes.

For me, the first iteration of this document is simply an outline of the SDLC that we use at my place of employment, with a list of roles associated within each step, a few examples of people who fulfill those roles, and specific checklists associated with each step of the lifecycle as well. I personally find checklists to be indispensable in training purposes, but also just about anything else I do at work. For example:

  • Project Manager (Joe) assigns you a task in Jira.
  • Set an estimated completion time on the task based on formula x.
  • Set the ticket as 'in progress' when you begin work on it.
  • Create branch from git, click link to view a 30 second video on this progress.
  • Write unit tests based on constraints in design document, see page y for unit testing naming conventions.
  • Set ticket for review and submit code to review system..' etc.

Your new employee should hopefully be familiar with the majority of the concepts, and now have a step by step guide of how the processes are applied at the company. I also do a quick demo of the process from start to finish using real documents from projects that I feel were well executed.

As mentioned, its also a living document, so sections can be expanded upon as it is identified that they need more information. The whole team should be involved in keeping it up to date. It can be a wiki, OneNote document, whatever, but something that all people can edit and review, then start to get other people involved in improving it when they've got a spare hour here and there. That way one person isn't doing it and propagating their own spin on the process to all the new hires.

Once they've reviewed the process, have them follow through on a small feature/bug fix on a non mission critical project and have them ask questions that the document doesn't cover. Record what these questions are, because they should probably be the first things you add to the document the next time you work on it.


You cannot combine doing something like this good without spending time. At least, if you want to do it yourself. You should ask yourself whether it is really necessary to document it as precise as you are trying?

The only alternative would be to let the new hires do the main job. Let them write some parts. The time you spend to correct these (in the form of feedback), will be less than in your current situations. Provide some good templates and you don't have to worry about lay-out.


I believe you already know that they have tasked you with mission impossible. As a writer you are probably already familiar with the quote from Mark Twain:

If I had more time, I would have written less.

Given virtually no resources, probably the best you can do is get a file cabinet and ask everyone to make a copy of what they already have and put the copy in the file cabinet. That way you can at least say to the new hire "If you want to look up something about the system the place to start is in the file cabinet."

Good writing takes time, period. Further it needs to be tailored to the target audience. What works for end users will not be what a programmer needs.

Not to mention that good training is not limited to written materials, it would include full gambit of educational resources including on-line, classroom, multimedia etc.

As they say, "If you think education is expensive, try the cost of ignorance."

Further it goes without saying that viewing documentation as something to be done after the fact rather than making it an integral part of the process from day one is indicative of a systemic organizational problem.


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