Sharing my experience of technical writing. The problems I faced and their solutions I learnt from others and with practice.

1. Technical Writing – My Experience
- Divya Sharma

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

3. 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’ )

4. Process of Writing
 Plan
 Write
 Review
 Rework
 Publish

5. 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!

6. 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’.. )

7. 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

8. 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.

9. 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

10. 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

11. 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

12. 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

13. 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

14. Example - 1
 http://www.cooking
forengineers.com/r
ecipe/178/Chocola
te-Cake

15. Example - 2
 http://www.taste.com.au/reci
pes/20016/classic+chocolate
+cake

16. 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

17. 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

18. The Secret Mantra
Keep Practicing
&
Enjoy What You Do!

19. Q&A

20. Thank You!
Happy Writing 