It seems that the worst aspect of any project is documentation - what developers have done, what contractors delivered, who owns what, how to support the end result, etc.
How do you encourage all project members to contribute to handover documentation?
There are a few ideas which can be used:
In bigger organizations dedicated person or team working on documentations often seems to be a good idea. It is possible to find people who like to write, use correct English (or whatever language you use) and are technical enough to deal with most of technical documentations.
It always help to have clearly defined handoffs within the project. For example we don't treat a feature as done unless it is documented or we don't treat a feature as ready to development until there's user story along with test cases. With clear criteria people will know that documenting effort is a part of their tasks.
Spread the documentation through the whole building process. Like in the previous point analyst/product owner has to prepare their share before developers start working on a feature, then developers prepare their part before it goes to QA staff, then QA staff work on their stuff before a feature goes to deployment and so on. With this approach you should have quite good documentation before the feature is considered as ready. If you work with this approach consistently the whole documentation effort seems to be less painful.
Standardization is also one of ideas which may work (although not necessarily will). With some standards which are set in the organization everyone knows what is expected in terms of documenting a project. Note: chances are good that you will have to remind people about standards and expectations for some time until they get used to them and will fulfill your expectations in this area with no pushing. Also don't make your standards too strict or too heavy or people would ignore them and you will have hard time getting docs you need and they will have hard time adjusting to your expectations (kind of lose-lose scenario if you ask me).
Use tricks which reduce burden with creating documentation. There are ideas like self-documenting code or writing requirements in a way which allows automatic or semi-automatic test case generation (this one depends on tools you use).
I am not a manager, so I would just like to share what motivated me in the past.
No one likes doing end of project documentation, but at my last company I entered as they were doing their first set of field tests. The firmware dev before me was on his own and did not do documentation.
After working for 3 years at a company and having to recode everything I document everything, and I will continue to. The amount of work it takes when there is no documentation really can be a good motivator.
My advice, when you have someone that does not understand the point of end of project documentation throw them into helping with a project that has insufficient documentation. If you are short on these projects, good job.
One way that I have found that works is to have the developer put together a presentation, and then present the results to the team, who will undoubtedly ask questions about how things work, where things are etc. This works because no one wants to end up going to a meeting unprepared and encourages communication, rather than have it be a solitary project.
Agreed, it is the worst aspect of the project. Ideally, this identified as a task within the project for each work stream to complete. However, I do favour having this as a specific work package assigned to a resource(s) who areresponsible for the creation and collation of documentation. In addition, it is worth having a specific standard to how it is presented.
Note that using a tools such as SharePoint, allows for easy checking in- & out- of documentation, and can easily be administered by the appropriate person(s).
For contractors I would think it is pretty easy: link it to payment - but make sure the criteria for acceptable documentation are well defined and the review process well understood and agreed upon before entering into the contract.
For team members it is a little more difficult, but by spreading the load, making each person accountable for their own contribution, defining clear roles and limits, and making it part of performance appraisal, I think this can motivate people.
One key motivator is comparing with others, so if other teams are doing better, showing a public tally of monthly scores might be an incentive for some to do that little bit more in the right direction.
Lastly everyone has different skills. So your best bet is to recognise which are the best people to produce the documentation and put less strain on the others. It does not let them off the hook, they still get appraised on it, but by shifting tasks to people who are happy enough to do them you'll probably end up with a better result overall (most cost effective, desired quality).
But in the end if you are landed in an organisation with a culture that screams against documentation, you are up for a culture change. These things are slow, need the support of key people and must be effected gradually.
This information should have been gathered during the project. It should be apparent early in the project if the project documentation will be a problem. Documentation writing skills are often not the best among developers. You may need a coach, writing assistant, or technical writer to assist with the task. Having been both a producer and consumer of documentation, I can attest that it is difficult to produce good documentation, and that good documentation wonderful to have.
Ongoing sources of this information includes: - who owns what should have been specified in the contracts; - what the contractors delivered should match what was specified in the contract, and delivery recorded in the status documents; - what the developers have done architecturally should be recorded in design documentation; - what the developers delivered should have been recorded in status documents; and - how to support the application should have been documented during development.
This information should be developed as the project develops. On-going management of the contracts and contractors should result in the desired information being available at the end of the contract. A simple document tracking contracted deliverables and there state should enable immediate determination of what the contractors delivered. Be sure to add out-of-scope deliverables.
Recording what the developers delivered may be more difficult as they may not file good status reports. For an agile project, tracking story delivery should give you good documentation. Track equivalent deliverables for other methodologies.
Support documentation has always been problematic. Ongoing hand-offs to a production team can be used to gather this information. The production team should require or generate run-books for the application. This should include how to deal with ongoing support. This documentation may be prone to rot on the shelf, perhaps more so for projects which require less on-going support.
I would consider hand-off of the projects repositories (content management system, bug database, wiki, etc.) a critical concern. This can be an invaluable trove of information. If you haven't contracted ownership of the code this will likely not happen. I would at least want the code in escrow. If you supplied the repositories, it becomes an issue of placing them into maintenance mode.
Documentation on how to setup the environments for development, building, testing, and delivery preparation is important for the maintenance team. This should have been documented early in the project and kept up to date. If your organization does multiple projects, try to standardize this as much as possible.
Developers are typically conditioned (in the pavlovian sense) that when documentation is suddenly being demanded that layoffs are on the horizon (and in these cases, waiting until after the last moment to document anything is a survival skill to delay getting laid off). It would be far better to slowly switch the company culture to document things as you go. This will involve an internal wiki as well as a more structured document system. If you have some boss who makes remarks like "we only want full and complete documentation" then you have to keep them away from the developers as that sort of boss will shut down any wiki they can find - and the requirement that docs be "full and complete" raises the bar for docs so high that no one will do them.
We’ve all experienced how managers and higher-ups dance around the fact that we’ll quit someday. The justification given for why a process should be documented is almost always “because you might be hit by a bus tomorrow” (or the less macabre “win the lottery”). Since neither is within the realm of reasonable probability, this transitional documentation is often half-assed with the understandable “you’ll have more things to worry about if I get hit by a bus” attitude. But imagine if the justification for documentation was different:
I need you to document this process in detail so that any yahoo can understand it a year from now after you’ve left.
I’ve never had a manager or higher-up ever put it that way. In fact, many people feel that’s an even more stolid justification than “hit by a bus”. But it isn’t; it’s just reality. Why not accept it?
I know that I forget things, and many other developers know they forget things, but the process of making documentation has become so painful for most developers that we'd rather go to the dentist. To get better documentation is going to require a culture change.
The problem with documentation (age old question) is that if it's created up front or anytime prior to completion, it will not be insync with the actual code or process - and if it's not in sync, it's value is greatly reduced and the group/person taking over maint doesn't trust it and goes directly to the code to determine what the documentation should have said.......so, following XP - don't create documentation tasks, let the developers follow TDD (or any similar agile process)...if you want to encourage them, make them the supporting group after the system goes live (and inform them prior) OR have the group/person taking over the maint develop the documentation with the developers.......code far outlasts any documentation created.
No one seems to enjoy the task is right. In that case, I like to make it a required task with time spec'd out for it. It should also be listed as a part of the deliverables.
