The Workplace Stack Exchange is a question and answer site for members of the workforce navigating the professional setting. It only takes a minute to sign up.
Sign up to join this community
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?
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:
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.
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!
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,.
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.
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.
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.
