Technical writing - my experience

Technical Writing – My Experience

- Divya Sharma

Agenda Problems Process Few things to consider Styling of the write-up Handy tips for Developers The Secret “Mantra”

Problems in Technical Writing I don’t find anything worthwhile to write From where to ‘START’? It’s just too obvious to write It’s about what I want to tell my readers It should be perfect when I write It must be very impressive (read ‘Complex’ )

Process of Writing Plan Write Review Rework Publish

1. Plan Ask yourself some questions

Who is my audience? – Varied Audience What would they already be knowing? What is the aim of this writing? What information readers can find in it? Why should reader read it? What should be the size of write-up? Where this information will be kept? What it took for me to understand the concept, I

am writing now? ... And many more.. More is better!

2. Write Just write what comes to your mind Do not concentrate much on formatting This phase is not for being ‘Aamir Khan’ ( read

‘Perfectionist’.. )

Improvements in Writing Follow question based writing style

Think of the questions that come to your mind when you read your write-up and then try to answer them one by one.

Explain with simple and analogous examples Use Jargons with care – Remember Audience Try to use ORID framework. Human brain

understand better this way. O – Objective R – Reflective I – Interpretive D – Decisional

2. Write Contd. Example 1 –

Mom, my leave has been cancelled due to a client visit. I know you will be very upset about it. I talked with my manager if someone else can handle my project’s presentation. But I know the best about my project, so he wants me to deliver that presentation. I’ll talk to Granny about it and explain her that it is important for me to be here. I’ll plan this leave in next week.

Example 2 – A new class called ExceptionHandler has been included

in .net framework. I found it pretty interesting. It can handle exceptions of various types such as IO Exceptions, Mathematical Exceptions, Array Exceptions etc. The class can also be used to create User-defined Exceptions. In this blog, I am going to explore IO exception in details.

3. Review Review your first draft yourself – Self Review Once satisfied, get it reviewed by others If the other person could understand what you

intended to explain, you are good to go Do NOT take review comments personally Review comments help your write-up get a

better shape

4. Rework Edit your draft after self review Edit your draft for others review comments Seek clarification if could not understand a

review comment When not sure if a review comment is right,

take advice of subject matter expert Continue with Review-Rework cycle until your

goal is achieved

5. Publish Publish it to the intended audience Consider the mode of delivery Consider the device of audience – printout,

web, mobile Take your readers’ reviews too Maintain your published articles Acknowledge and reply to reader’s

comments/questions

Things to consider Use small sentences Use simple language Be clear and concise Avoid spelling errors and grammatical errors Use visuals in text not vice-a-versa Frequently Asked Questions (FAQs) do help sometimes Keep appendix for what you want to explain but not

here Think of the occasions when you criticized a teacher

for explaining a simple thing in a very complex way Think of the occasions when you praised a teacher for

explaining a very complex thing in a simple way

Styling of Your Write-up Small paragraphs Numbered / Bulleted points One standard font type and consistent font size Use consistent formatting for highlights,

headings, bullets, numbers, paragraphs etc. Keep the code snippets in same font/format as

they appear in editor for better readability Table is a useful tool for converting a

paragraph in a more understandable format Flow charts are best suited to explain a process Use good quality images

Example - 1 http://www.cooki

ngforengineers.com/recipe/178/Chocolate-Cake

Example - 2 http://www.taste.com.au/

recipes/20016/classic+chocolate+cake

Developer Handy Tips - 1 Always keep a notepad, word doc, etc. on your

system to take a quick note. Keep logging highlights of your module there Keep logging the errors/ exceptions you faced Keep logging which URLs helped you

understand issue or find solution Any useful URLs for more information All this information will help you when you

want to write about your learning

Developer Handy Tips - 2 Write proper and useful comments in your

code You should be able to understand it even

when you see your code after an year

Take your daily dose of learning Share it with others to increase your dose Be open to learn from your colleagues and

juniors too

The Secret Mantra

Keep Practicing &

Enjoy What You Do!

Q & A

Thank You!

Happy Writing