Improving documentation skills

[Pradeep bhatt]

My documentation skills are pretty ordinary. Can someone suggest how to improve it.

[Mark Herschberg]

This is one of the best questions I've seen posted here in a long time; thank you for asking it. :-)

1) Learn to write.
We all learn the basics of writing in schools, presumably we're all literate, but it's important to get to the next step, learn how to write. This goes beyond knowing basic spelling grammar and punctuation of any of the languages in which you work. In English for example, you should understand things like active versus passive voice, first/second/third person narratives, how to footnote, etc. I can't tell you how many people (granted myself included in casual writing like emails and JR posts, although I hold myself to a higher standard in my business communications) switch between tenses or perspective as they move from sentence to sentence!

2) Learn how to present
When should you use a list? a graph? Is a picture really a thousand words? Understand the different means of presenting information in textual form and the strengths of each.

3) Understand your audience
I use very different styles for internal architecture documents than I do for user guides designed for people like my parents.

4) Understand the context
No word stands alone. There are over 30 types of documentation that may be used on software projects including emails, tech specs, requirements, architectural documents, coding requirements, user manuals, code comments, the code itself, release notes, process guides, etc. Understand where best to put the information and how it fits into the larger picture supported by other information.

5) Learn by example
Read other forms of documentation (be it user manuals, specifications, memos, code comments, etc.) and see what you like and don't like about the pieces you read. Ask yourself why something is well or poorly written; ask others too. Reflect on this and incorporate into your own knowledge base.

6) Additional training
There are thousands of books, articles, courses, websites, etc. that you can use to supplement your learning. As with coding you learn most by doing but these resources help accelerate that processes.

Writing (along with it's sister skill public speaking) is a critical skill that will greatly impact your career success.

--Mark

[Raghavan Muthu]

That's a great and beautiful narration by Mark.

I would suggest a few more things. May be it could fit on top of all suggestions given by Mark. Just like a cherry on the ice cream!

#1. Try to review the same documentation what you have written. You yourself can catch some places wherein you can improve it either by rephrasing it or including some other better terms to present the same context etc.,

#2. Try to have an analogy which closely resembles to the real world examples so that it would be easy for the people to correlate with the well known things.

#3. Be descriptive and mention in detail wherever required. It intern adds more values and avoids confusions as you avoid the chances of taking the user for granted to have his/her own assumptions. It really helps in terms of requirements and implementation details.
[ June 26, 2008: Message edited by: Raghavan Muthu ]

[Pradeep bhatt]

Thanks Mark for the reply. You have rightly said that public speaking skills along with writing skills are very important. I need to acquire these skills if I have to grow.

I have always shied away from documenting. From the beginning of my career and also recently, I had an opinion documenting is boring job , does not require much thinking and technical skills matter more. Now I realize that I was wrong. Recently I was handed over some doc work. I was struggling and didn't know what to write. It was more challenging that doing tech work.

Let us take the example of most common section in docs, "The Introduction" section. I could just write couple of sentences here. As usual the doc went for review, someone else rewrote (obviously not being happy with my short writing)the whole section making it one page full. I read each sentences written and there was nothing that I didn't know. The important question is why I couldn't write so much. May be I should pratice more or my English is good enough. Not sure what the problem is.

You have raised a good point of presentation. Isn't there a saying "A Picture is worth 1000 words". Some things can be easily conveyed through drawings rather than words.

I would to pratice during my free time. What should I write ? Any suggestions ? Will blogging help ?

Mark, You said that there books, articles , websites which can help. Can you name some.

thanks

[Raghavan Muthu]

Originally posted by Prad Dip:
What should I write ? Any suggestions ? Will blogging help ?

Yes, definitely but not to a greater extent as many bloggers have that habit for entertainment sake and you may not really get a chance to get it reviewed or corrected. Perhaps, it may be one of the channels which you can make use of!

Going through the journals or articles would also be of some help!

[shan Iyer]

Originally posted by Prad Dip:

I would to pratice during my free time. What should I write ? Any suggestions ? Will blogging help ?

Haven't you heard books are man's best friends ?

Read, read and read.....start reading whatever you can get your hands on to . Keep a latest Oxford dictionary always with you, because in the beginning there would be so many words you haven't come across. Cultivate reading habit, its very very imporant. I too dind't have it but have just started . Stretch your mind, expand its horizons. Start with the interesting articles and editorials in the morning newspaper. Apart from the usage of better words concentrate on the sentense formations also. Thats also very very essential . RK Narayan always used simple words in his novels but formed beautiful sentenses with them !
[ June 25, 2008: Message edited by: shan Iyer ]

[Mark Herschberg]

(Note: I can only make recommendations for the English language as my writing skills is other languages are mediocre at best.)

"The Elements of Style" y William Strunk and E.B. White is considered the classic in this field having been used for millions of people for decades. It's short and cheap and designed as a reference book.

There are lots of other books including many designed for business writing. A web search will also turn up websites with grammar and spelling exercises and games.

At the risk of sounding like a broken record, consider open source projects. Documentation on open source is notoriously poor because most contributors want to work on the code. I hear that people who contribute to writing are well respected as people who take on the tasks most other people don't want to do.

I'll also bring up my usual plug for Toastmasters (they are all over the world) for public speaking.

I know throughout the US people form writing clubs. Groups of people get together to sit together and write, bring in what they've written for peer review, and to talk about issues relating to writing. You can start your local club (if you're not sure how consider modeling it off of the Toastmasters program, but for writing).

--Mark

P.S. There is a saying that "a picture is worth a thousand words" which is what I was referencing. However it's not always true. A confusing picture might be worth negative words (better off without it). A good picture might be worth many thousands, while others maybe a few hundred. The point is, understanding how to communicate means more than words, it includes when and how to use other video aids and outside references.

[Mark Herschberg]

I'd also check out Edward R Tufte, he is a leader in the field of information/interface design.

I read his analysis on what went wrong in the challenger disaster (in fact I help teach it at MIT) and I think it's a great example of how poor communications caused a large scale failure.

--Mark

[Raghavan Muthu]

Originally posted by shan Iyer:


Haven't you heard books are man's best friends ?

Read, read and read.....start reading whatever you can get your hands on to . Keep a latest Oxford dictionary always with you, because in the beginning there would be so many words you haven't come across. Cultivate reading habit, its very very imporant.

I too agree with Shan Iyer and would suggest the same! .

[Pradeep bhatt]

Thanks Mark. I will surely buy "Elements of Style" book. Contributing to open source project documentation is a good one.

[Pradeep bhatt]

Originally posted by shan Iyer:


Haven't you heard books are man's best friends ?

Read, read and read.....start reading whatever you can get your hands on to . Keep a latest Oxford dictionary always with you, because in the beginning there would be so many words you haven't come across. Cultivate reading habit, its very very imporant. I too dind't have it but have just started . Stretch your mind, expand its horizons. Start with the interesting articles and editorials in the morning newspaper. Apart from the usage of better words concentrate on the sentense formations also. Thats also very very essential . RK Narayan always used simple words in his novels but formed beautiful sentenses with them !

[ June 25, 2008: Message edited by: shan Iyer ]

I feel that in newspapers lot of words/sentences get repeated. What I mean is I won't be reading new things. They talk about the same things again and again.

Yes, sentence formation is where I am struggling. I can't think of writing something new. I use the same sentence always. I should have concentrated on these things many years back but as they say "Better late than never"

What about Reader's Digest book ?

[Chetan Parekh]

Originally posted by Prad Dip:


I feel that in newspapers lot of words/sentences get repeated. What I mean is I won't be reading new things. They talk about the same things again and again.

Yes, sentence formation is where I am struggling. I can't think of writing something new. I use the same sentence always. I should have concentrated on these things many years back but as they say "Better late than never"

What about Reader's Digest book ?

Reading The Economics Times and watching business channels helped me a lot.

Apart from that I read books on different subjects to gain better visualization and explanation power.

[Arjun Shastry]

Pradeep,check your PM.