I not sure if it is me but seen like developer don't really like to document because they find it easier to explain things briefly instead of documenting it down and from time to time have to update the document.
And another thing is that
consultant come up with use cases for different functionality should they then also write the underlying technical implementation or it should be left entirely up to developer team to decide and work on the technincal implementation?
I say leave the documentation to the technical writers. Developers write code not documentation!
Seriously though, if there is a real need for developers to write/update any kind of documentation (functional specs, user docs, etc) I think a good approach would be to do it sooner rather than later. Many people tend to put off distasteful things like writing documentation and end up having to write up hundreds of pages by tomorrow. Much easier to do it iteratively.
If you have a clear separation between:
, the technical documentation is better written by the developer team, or by an external redactor (technical writer, as jpoh calls him) assisted by the developers.
That way, the architects or consultant can think about use cases without being influenced too much about technical issues. The applicative architects must transform functional specifications into technical specifications, and they will have to incorporate non-functional requirements.
That is why those functional consultants may not be the best equipped to write technical documentation.
The over-all system-documentation should be written BEFORE you start coding. It's much easier to talk about the design og the system when it's documented, it is easier to discover design-errors, and they are incredibly cheaper to fix. And if there is a written system-design, every developer will have the same goal. Well, closer to, anyway.
And of course, if documentation is the first step (in stead of the last), you can't just drop it.
When it comes to the details (classes, methods etc.) I rely very much on self-documenting code. If you can't describe what a method does with a short name, it's probably too complicated. If not, add a bit of inline-documentation. (Javadoc or similar) This forces good design a bit more, and it's much easier to have everything right there with code completion in your IDE, than long boring documents somewhere.
As a developer, I do NOT want detailed documentation AT ALL! If it is needed, don't write it. Fix the code! (Refactor)
We've written a JUnit test that goes through our sources looking for methods without Javadoc. Any method that is added with no Javadoc causes the test to go red with an error message saying
a) which new methods are missing Javadoc
b) the people who last touched the class with those new methods (using an SVN call)
Works well for us.
Split your team into 2 groups. One group will be the 'developers' who must write documentation, unit tests and the code. The other group are testers, who must write integration tests and test plans from the documentation.
Both groups start at the same time, forcing them to work together to build a testable project, and as all functional testing will require detailed and correct specifications and implementation plans with change control, the 'test' group will be able to help the 'developer' group to produce the documentation artifacts you need.
At the end of the project, switch groups.
Anyone that doesn't want to work this way, you can discard as not wanting to be a professional software developer.
Necessity is the mother of invention.
Always escalate undocumented issues to the developer. The developer can either answer the same questions over and over, or put the answer in the documentation. When support personnel escalate to the developer, they can explain where they looked to get the question resolved. This way the developer can learn how to (re)structure the documentation so people can get to the answers more efficiently.
In this way the developer learns that the better a job the documentation does speaking for them, the more worthwhile it is to write documentation, and what makes that documentation useful. A pro-active developer will learn to write things up sooner in the process.
Too often software is provided with inadequate documentation and no recourse to bother the developer with questions from the unwashed masses. While the developers of this software may have more time available for churning out code, their software has an un-addressed barrier to adoption.
I think that lack of documentation is a process smell more so than a developer smell. Usually, it means that they haven't spent enough time trying to explain it to other people. Code reviews are useful for this, but programmers also need to understand the utility of simply explaining things to other people as early as possible. I recommend watching The myth of the genius programmer.
I've found that once I get past this barrier, writing documentation is much easier.