30

I am serving notice period in my organization, and a project manager has asked me to write down a document on what I have done. I have briefly mentioned the points on which I have worked, but I have not done any "in-code" analysis. He is not satisfied with the document, he says

The person who is taking over must be able to understand what was done by you theoretically and technically.

What should be my approach towards it be?

  • 9
    If you started a job and someone gave you bullet points with no walk through of the any of the systems, the architecture and the implementation, how would you feel? You need to give someone the type of information you would like to see if you were being inducted in a new organisation. You will need to deep dive a lot further than a few bullet points. – Jane S Oct 20 '17 at 6:16
  • 15
    @JaneS I would feel like a normal day in a yet another existing system without documentation :). However I think that the project manager should set an objective on what should be in the documentation. OP could write a lot, but he is in notice period, as such it's better to focus on eventually less but more relevant content and make sure to have it validated. – Walfrat Oct 20 '17 at 7:51
  • 7
    Asking how to write technical documentation seems beyond the scope of this site, and this question seems too broad. Why don't you just ask your PM what he expects? What's the worst that can happen? You're already on your notice period. – Dukeling Oct 20 '17 at 8:11
  • 3
    Possible duplicate of My employer wants me to write a guide for doing my job – gnat Oct 20 '17 at 9:12
  • 4
    Very related: How can I prepare for getting hit by a bus? – David K Oct 20 '17 at 13:17
44

You're writing what's known as "Handover Documentation". The aim of this documentation is to pass knowledge of how this software works and how it's written, maintained, and deployed to people who will follow you.

There's a related question/answer over on Stack Overflow that generally covers the topics that you need to address in your own document:

What are the core elements to include in Support Documentation?

Quoted in part:

• The documentation of the code (javadoc, doxygen, etc)
• Details on build process
• Where to get current source
• How to file bugs (they will happen)
• Route to provide patches either to the source or to customers

• How it works (simple, but often overlooked)
• User-customizable portions (eg there is a scripting component)
• Primary contacts for each component, aka escalation path
• Encouragement for feedback from Support as to what else they want to see

Also consider:

  • System/User credentials required (don't put the passwords into the documentation!)
  • Where the dev/test/UAT/database/any other associated servers are
  • Where the production server is
  • Deployment steps
  • Whether there's any licences involved
  • Location of original requirements/analysis documents for each piece of work

Googling "Handover Documentation" will also give you more insights.

To save time, I'd write up a series of bullet points (as above and from your own research according to this project) and present them to your PM. Ask him to tick off the ones he wants to see and add any others that he feels appropriate.

  • 12
    Getting the PM to tick off what he wants is a great ideal. Altho you run the risk of him saying "Everything! Yesterday!" :-D – G. Ann - SonarSource Team Oct 20 '17 at 12:00
  • This can depend on time constraints; some things might be more important than others. There might already be documentation to cover some of those headings as well. – Snow Oct 20 '17 at 12:02
  • Despite what manager might think, usually the first point (code documentation) is by far the least important. When you need the source, you can't guess where to get it or which one to take. You either know or you don't. The builds are sometimes extremely tricky as well. The code (if it's not terrible) should be readable anyways. – Džuris Oct 21 '17 at 8:08
  • As a PM myself, 90% of the things you listed I expect to have already been written by myself as a PM. – motoDrizzt Oct 21 '17 at 15:39
19

I'm going to take a slightly cynical, devil's advocate view...

Snow's answer lists a whole lot of good stuff that should be documented, but nearly all of this should already be documented, and continually being kept up-to-date. If this documentation doesn't exist (and I know there'll be plenty of places where it doesn't), then that's essentially a failing of your management not to get the right practices put in place during your time with the company. If that's the case, them trying to remedy their failure by "dumping" on the person who's leaving the responsibility of "documenting everything" is not good.

Kilisi's answer suggests "Do it how you would want to read it if you were taking over" which is again an nice ideal, but should perhaps be tempered with consideration of what you were given on day one. If you were given next-to-nothing, e.g.: "there's the code, if you can't work out how something works, ask someone", and the situation hasn't changed since you've started, again, it's not really the responsibility of the person leaving to fix bad practices.

The gist of what I'm trying to say is: if it applies, don't get bullied into trying to fix inherently bad practices.

  • If most things are already documented in good detail, your "handover" should be relatively short; the handful of things "in your head" that others might not be fully aware of. You will know best what these are, but should seek guidance from your project manager over any specific areas they are interested in.

  • If existing documentation is sparse, out-of-date or non-existent, then it's not your responsibility to fix "systemic failure" as you leave. Brain-dump what you can, to help the poor sod who replaces you, but don't feel guilty because this situation should have been tackled (by management) long ago.

Of course, if you've deliberately "hoarded" information that only you know, and not kept existing documentation up-to-date, then it should be your responsibility to finally get around to passing that information on in the most helpful way you can!

  • 5
    I agree it's not practical to fix it on your last day, but I strongly disagree that it was up to "management" to get documentation put in place during your time at the company. It's your personal responsibility to document crucial data regarding your job while on the job, whether or not management says to—just as it's your personal responsibility to do a good job in the first place. It's a matter of ethics, not morals. – Wildcard Oct 20 '17 at 17:08
  • @Wildcard. It's a joint responsibility. Yes, a programmer should document everything, but we also know lots of them would rather get on with the next bit of "real" work. Management can help by making the process as painless as possible, encouraging a culture that wants to, and enforcing it where necessary. – TripeHound Oct 20 '17 at 22:10
  • 3
    @TripeHound ...not to mention that documentation is the first thing to go whenever things get rough. When there's a choice between meeting the deadline, or staying in the budget and getting documentation done, the documentation falls by the wayside every time, and that's usually at management's direction, not because that's how the technical resources want it. – HopelessN00b Oct 21 '17 at 1:37
  • @HopelessN00b True. And the main thrust of my answer is if, for whatever reasons, whose ever "fault" it was, a company finds itself "under-documented", expecting someone leaving to magically "fix" things is not reasonable. Other answers cover very well what to do if everything is as it should be. – TripeHound Oct 21 '17 at 5:36
  • 1
    @TripeHound we are in complete agreement. – HopelessN00b Oct 21 '17 at 5:40
5

What should be my approach towards it be?

Do it how you would want to read it if you were taking over. Apart from that just serve out your notice and focus on where your career is heading. Unless your boss is giving you a format to follow there isn't a lot else you can do that he/she will be completely satisfied with.

I normally do a step by step walkthrough of all my tasks assuming it needs to be followed by a beginner. So no abbreviations, no slang etc,.

2

The most important stuff I'd like to know when I take over from another developer is the common "what, why, how" of the project. That is:

  • What is it? What does it do?

  • Why did you choose to do things a certain way? I'll always wonder why a developer decided on a certain framework or language and context or warning about certain things I hadn't considered are invaluable.

  • How does the project solve the problems listed?

The other most important thing, is to get a fresh machine, nothing to do with the project and try get to a working setup on it (just as they'll have to do when they take-over).

You have no idea how many times I've asked an ex-project dev why their documentation didn't work and they'll be like "Oooh, yeah, you just need to add this environment variable, I'd forgotten that." It's normal and human to not note every step in an install, but will make life so much easier on the next dev given you're in the right mind-set now.

2

Just imagine you're doing a knowledge transfer with another developer that will pick-up where you left. Normally, you'd go through the code at a high-level and mention anything of interests, particular pain points, places that often have bugs, etc. This will give you starting points to create the documentation.

Since this is a written document and the next employee won't be able to ask question, you may want to be more explicit than you would giving a verbal overview.

1

Is the person taking over your tasks already working for the company, or will he/she have some overlap with you?

If so, let that person review the documentation if it is good enough for him/her. (Or if you have a colleague that can help out.) It is impossible to cover everything so focus on the hard stuff, the odd stuff, the exceptions to industry standards and so on.

And I know it is boring and you have probably mentally already left the company. And depending on why you left more or less loyalty to the company. But I suggest working iteratively so you have shorter goals, and request feedback often. Since you have limited time left and the company should utilize you as efficiently as possible, writing unnecessary documentation is a waste, and they might miss out on the important stuff.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

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