I just started a new job as a technical project manager. It's more or less my first experience, as I have just run teams of two students before, and now I am managing a project of 10 engineers, some of them are even more experienced than I in their field.

I noticed that there is a huge problem with documenting their work, as the previous manager didn't think it is necessary. This costs us a lot of time and money if any member leaves the team.

The question is how can I push my team members to start documenting their work from an early stage, knowing that it is very close to technical software development?

  • Get the boss to pay them for writing documentation, and even then only 1 in 5 will be interested. It is not really a developers or engineers role to document any thing, but to implement the document. Its the wrong way around.
    – Piotr Kula
    Commented Jan 25, 2016 at 15:35
  • How confident are you that the training of new members to replace ld ones that leave will outweigh the cost of the documentation? I've been on projects where documentation was by far cheaper, and I've been on teams where documentation was surprisingly ineffective due to the nature of the team. You very well may be right, but sometimes it helps to put a skeptic's hat on and see if maybe one of your own assumptions about how the world works needs maturation. Its a good test before suggesting that others need to change their process. Much cheaper that way.
    – Cort Ammon
    Commented Jan 25, 2016 at 22:16
  • @CortAmmon a very interesting point. I admit i never looked at it this way. However, it is quite complicated to answer as documenting has to be payed by my project (which is finnancially bad for me), however, the training will be payed by the team budget which is not my responsibility. I think i need to look more into it Commented Jan 26, 2016 at 7:31
  • Having people switch roles occasionally will make them really notice whether there is documentation.
    – Owen
    Commented Feb 1, 2016 at 23:01

8 Answers 8


Documentation is always the stepchild of development. Although you could simply order them to do it, there are a few points to take care of when you want to motivate them:

Demonstrate the problem

Have they ever seen the problem? Right now it's an abstract problem. You think something might happen in the future. You will have better chances if you can provide a real example.

Do you remember the problems we had when Steve left?.

Positive Thinking

You need to give it a positive spin. If you ask people to document, because it gives benefits to those that stay if the person leaves, we can agree on the fact that that's the professional way. But on a personal level, nobody cares what happens to the company after they leave. So you should turn it into something that benefits them while they are still there.

We should document more so Steve can have his 3 weeks vacation without us having to call him every other day because we don't know how it works.

Try to put it in a light were it's in their best interest, not only the companies.

Make it easier to do the right thing

Grant them the time to do it. Nobody ever told me to not document. But every single project manager I had, always wanted me to finish in less time than it would have taken to do it properly. And the only thing you can skip without losing the customer is documentation. Don't expect people to do work they hate in their own unpaid (or even paid) overtime. You want it done? Plan for it and make it part of the project result.

Lead by example

Is your work properly documented? Who can take over if you get hit by a bus? You cannot expect people to be motivated to do something they dislike, when you don't do it yourself. And I'm not talking about a project plan. That's your product, like other peoples source code. I'm talking about what made you write exactly this project plan (or backlog). Why did you do it? What tasks are still open? Anything that will help replacement-you to do a proper job when you hit the lottery and are off to Hawaii for the rest of your life.


You've identified a risk, and a possible solution. I'd refrain from considering your solution (more documentation) as "the" solution and ask them to apply it straight away. You're working with a team of experts, which will likely have a different point of view on the matter, so do not expect to be able to "motivate" them into doing what you want... engage them in a discussion about the problem and ask them to think about a solution, it's way more effective.

  • 1
    Quite logical and yet might not be the proper way. Their fear of documentation is from their self-protection. Every member is trying to make his position more valuable and himself vital to the team. Beside, documenting also means more work. Si i think i need to show them they need this documentation just as everyone else Commented Jan 24, 2016 at 13:33
  • 1
    @Mamoo is right. You are not going to impose a solution on them. A project manager almost never has authority to impose a solution and even saying "here's a solution" won't fly. Commented Jan 24, 2016 at 18:30
  • you are expressing a strongly negative attitude - i caution self-awareness when discussing the matter with them, otherwise you will simply lose them and isolate yourself
    – gef05
    Commented Jan 25, 2016 at 6:53
  • I see your point, and yet if I get it right you're asking them to choose between their self-protection, and your interests (that is the interest of the company which you bring in as a PM). On which would you reasonably bet?
    – mamoo
    Commented Jan 25, 2016 at 10:09
  • @gef05 I really don't get your point by saying that requiring a documentation is a "strongly negative attitude"! Please clarify Commented Jan 26, 2016 at 7:32

@Mamoo is right. A new and junior project manager does not have the authority or influence to jump to a solution and ask the team to implement it. Even as a two decade project manager I wouldn't try to impose a solution on the team.

As PM you have to help them to find their own solution. To do this you first need to get them to identify the problem. Until the acknowledge that there is a problem, they won't even be willing to consider a solution.

Retrospectives are an excellent way to do this. By guiding the team through an examination of what is going on with the project, you help them to uncover the problems themselves.

Something as simple as the Speedboat/ Sailboat game can do this. You can also go to TastyCupcakes.org and look for retrospective games. You want to focus on exercises that reveal problems. Even the simple "What Went Well, Things To Look At" two column brainstorm will get you farther than telling the team "It's the documentation."


I think you mean Knowledge Management? I am in the same position. It is a nightmare trying to keep processes and knowledge up to date, so if the tacit knowledge leaves it is not the end of the world. Somebody else can pick up and do that job, without a risk to the information systems, people and components necessary to carry out the work.

We use confluence. It is an open source wiki. People update this and is is accessible to everyone in the organisation. Once someone adds an entry it is peer reviewed from a QA perspective. I used sharepoint for this in a previous organisation. Work instructions and Process maps were designed to work parallel to one another. It is a must for organisations now and it is absolutely essential that this is managed.

I recently did Lean Six Sigma for this. I got a certificate from studying it through distance learning. It helps you analyse your processes, reduce variation and take out the non-value stuff.

Hope this helps.


NO! You can't force them, it's not their job. It is your job (or project manager's job).

I am a software developer, and if somebody told me to document the process of how the system works I wouldn't do it.

(Actually I have been asked many times and told them to shove it, resigned or had a massive fallout - Because I knew the proper way it should be done without cutting corners and costs)

That is the job of the project manager, to deliver the specification to me, so I know how to do MY job, signed off by the big bosses. So that later it's not, why did you this and I thought you would do that. Bugger that.

What you are experiencing is a very common problem, where somebody wrote some code to do something and it turned into a business, dogs arse forward (in reverse). The developer wrote code based on what the boss said and now the project is so big nobody knows nothing.

The solutions is:

  • Source Control (TFS or GitHub)
  • Ticketing system. Jira, TFS tasking, Kanbanary, whatever.
  • Central drive with documents or online Wiki

Project manager creates documentation to accompany the ticket/task, and makes sure it is updated in the main specification document. (Usually Business Analyst does this.. but lack of BA responsibly falls on PM)

Project manager manages it all, developers check in work and pick tickets or PM assigns tickets to dev if the devs are "tools" and can't be responsible and pick tickets themselves.

  • Absolutly right!
    – Ewan
    Commented Mar 27, 2016 at 18:40

I think the best way to motivate people to start a work is involving them in decision making. If they participate in the process of decision making and they choose a solution, they will understand why that work should be done and as a result they will be more committed. Documenting is boring unless you feel the essence of it.


Most of the sentiments in these answers I agree with. If you have a SDE, or a team of SDE's it is best to keep them writing code and the less time they spend writing documentation, the better. Ny the time someone is writing code the documentation should (mostly) be in place. That said, there are strategies that can be used to keep code properly commented (another form of documentation). The strategy we use is a form of "continuous quality". We use a software solution called Sonar which analyzes code when it is checked in for many different things: naming conventions, repeated lines of code, comment volume, etc. If the comment volume is too low we take a look and make sure the code can be read and understood by a dev who did not write it. If not, the commenting needs beefed up.

If on the other hand, your team is not composed of SDE's, but rather the people designing the system (architects, DBA's, etc), then you do need them producing good documentation, and once strategy to get them to do it is by enlisting one of the downstream consumers of said documentation to vet what has been written. If the documentation is unclear or too sparse, you have an actionable item with a gatekeeper to boot. Make sense?


In most cases, if not all, evidence of strong documentation is consistent with a high performing, mature organization and lack of documentation is consistent with an immature, low performing organization. This is why various maturity models have a HUGE aspect of documentation to it. Who gets to create the documents depends on who is the best role to document, which is usually who does the work. It is simply part of the job and part of the job description.

Every role out there has aspects to the job that no one likes and wishes could be pawned off to someone else...or a silly argument is made that it is not necessary.

If your culture has supported a lack of documentation, then change the culture and that requires top level sponsorship. Simply make it part of the job description and part of their evaluation. Those who don't like will eventually be selected out and vice versa.

Every job, including developers of code, has tasks that are undesirable. Get over it.

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.