Technical writing - my experience


Published on

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

Published in: Business, Education
  • Be the first to comment

No Downloads
Total views
On SlideShare
From Embeds
Number of Embeds
Embeds 0
No embeds

No notes for slide

Technical writing - my experience

  1. 1. Technical Writing – My Experience - Divya Sharma
  2. 2. Agenda Problems Process Few things to consider Styling of the write-up Handy tips for Developers The Secret “Mantra”
  3. 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. 4. Process of Writing Plan Write Review Rework Publish
  5. 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. 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. 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. 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. 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. 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. 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. 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. 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. 14. Example - 1 ecipe/178/Chocola te-Cake
  15. 15. Example - 2 pes/20016/classic+chocolate +cake
  16. 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. 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. 18. The Secret Mantra Keep Practicing & Enjoy What You Do!
  19. 19. Q&A
  20. 20. Thank You!Happy Writing 