A client recently posed this question (and 4 others) to us - the internal discussion regarding this question is interesting ...
[AD: ]
Being able to communicate is the skill. I like a Process MeNtOR deliverable as it forces people to put their thoughts down and gives visibility to others. At the end of the day whiteboards/photos/wikis etc are aids but if someone has a clear understanding to document takes little time. I believe in pragmatic process and adapting to suit the project and team but strongly see that communication and documentation skills are vital.
[AB:]
A brain, a copy of Enterprise Architect and the mentor System Architecture template should get you most the way there.
[SM:]
a. Yes a training course is good, because it makes it formal that delivery of good documentation is seen as a standard requirement
b. Exposure to standard design templates
c. Learn how to do reviews effectively – very important
[JE]
There are certain things you need in your toolbox to write good documentation for a technical system:
- A lingua-franca formal modeling language and a tool to support it, we use UML and Enterprise Architect
- A free-form diagram tool – we use Visio
- A common document format – we use MS Word
- Appropriate templates and guidance
- A clear understanding of the documentation process, and where the document you’re writing fits in it
You need the common language and tools so that everyone can work together, that simple. Choice of tools is usually organisationally driven, the ones we use are the best-of-breed at the moment. There should always be scope for evaluating new tools / using domain specific tools in particular cases. We as an organisation consider UML a prerequisite for a designer.
It’s important that the technical staff doing the authoring aren’t asked to do repetitive tasks which don’t add value to the document / project, but also that they are given a clear understanding of the level of detail expected in a technical document. Thus, to get good documents out you need high-quality worked examples for others to learn and copy from – we use Process MeNtOR templates and I have a personal library of some good ones I’ve done in the past. I know from the old-boys-network where to get some really great examples. Experience teaches the pragmatic authoring of documents – most of the MeNtOR documents I have produced on are not complete vs. the template, but do include all the relevant information.
Once Documents have been completed, constructive review is a really good learning experience. I can’t stress strongly enough how important it is that reviews be conducted in a mindset of constructive technical criticism, since negative review experiences will mess up the process and staff morale.
I can’t comment on the professional writing course, I haven’t done it yet! Perhaps that’s why my writing is so unstructured.
[SW]
Mentoring and practice. Some basic training (ie. Process MeNtOR)
[LC:]
To do good documentation, the first skill is to be capable to understand it yourself first (this is properly the hardest); the second skill is to be capable to know what the audience needs to know; the third skill is basic business writing skill; the forth skill is to know UML and other technical diagram standard.
[MC: ]
I think the MeNtOR deliverables help a lot, but the main aim of any documentation is communicating a set of ideas. Who’s your target audience should be the first question asked. Something destined for the business is very different to something aimed at the dev team (or at least it should be). Having a common language (UML for most diagrams, a domain “language” for the business) is vital, otherwise something which you believe is quite clear, is quite confusing to someone else.
Again, I think this is somewhere that a mentor can help guide you through what’s helped them in the past. Learn from someone else’s experiences.
[MP]
To foster documentation skills, designers should not be involved in coding the solution; they should be in an advisory role only. This forces them to put down on paper enough detail that another developer can code to.
The knowledge that they will be coding the solution they are designing, means they know they can worry about the issues during development phase. This means less thought goes into design, issues may be missed, documentation is less, much of the detail remains undocumented.
Carl Rogers - Principal Consultant & Process Development Architect