Technical Writing 101

Getting started with Technical Writing especially for developers.

Transcript

1. Technical Writing 101
2. Frontend Developer @Hotels.ng Technical Writer - dev.to UI Designer Twitter - @sarah_chima Sarah Chima
3. What we will discuss 1. What is Technical Writing? 2. Why Write? 3. What to write about 4. Common Excuses not to write 5. Before you write 6. Steps To Write Technical Articles 7. Tips on Writing 8. What to Expect 9. Moving on
4. What is Technical Writing?
5. What is Technical Writing? • Writing about technical or specialized topics. • Providing instructions on how to do something technical. • Writing that helps users solve problems with technologies or technical subject matter. • Documentation of complex technical process or ideology into simpler understandable formats.
6. Main Purpose of Technical Writing 1. To break complex technical information into simpler understandable formats. 2. To make such information more usable and accessible to those who need such information.
7. Examples of Technical Writing • API documentation • Framework documentation e.g reactjs, vuejs • Tutorials • Review of Technical tools • Personal experience, motivational writing for techies
8. Why Write?
9. Why Write? Personal Development • Constant Learning • Improved communication skills
10. Why Write? Job Opportunities • Work as a technical writer in a company like Auth0, X-team. • Write articles for technical blogs like Scotch.io, LogRocket, Pusher etc
11. Why Write? Online Presence
12. Why Write? Online Portfolio
13. Skills Needed To Write • Technical Skills • Communication Skills • Research Skills
14. What To Write About?
15. What to Write About? Projects You’ve Built
16. What to Write About? How you solved a challenge
17. What to Write About? New Concept Learnt
18. Common Excuses not to write
19. Common Excuses not to write Excuse 1: People have written about almost everything
20. Why you can still write: • You can go deeper on a subject • Make it simpler • Do something different e.g use better illustrations or examples • People around you might relate with your content more than others
21. Common Excuses not to write Excuse 2: I have no time
22. Why you can still write: • Make out few minutes each day to write • Research on what you want to write at other times
23. Common Excuses not to write Excuse 3: I am an amateur
24. Why you can still write: • Nobody knows unless you tell them • Writing doesn’t mean you must present yourself as an expert. • Share what you’ve learnt. Give your opinion and do not advice as an authority. • You will explain beginner concepts as a beginner more than a more advanced writer
25. Before you write: Decide on a theme for your blog. Find a niche. Don’t be a generalist.
26. Before you write: Think about the tone of your writing - casual, formal, semi-formal
27. Before you write: Think about your audience
28. Steps to Write Great Technical Articles 1. Research 2. Code 3. Writing 4. Code Review 5. Grammar review 6. Publish
29. Research Find out all you can about a topic, what others have written and things they’ve not. Find out how you can improve what has been written. Make headings from your research
30. Code If you are writing a tutorial, work on the project first and make sure it works.
31. Writing 1. Headline 2. Introduction/Quick Summary 3. Requirements 4. Multiple step explanation 5. Examples 6. Tips 7. Summary
32. Headline Choose a headline that describes the content of your article.
33. Headline Make it catchy, Make it short
34. Headline Use a verb e.g how to do X
35. Examples of good Headlines Build Custom Pagination with React Get to Know React's New Context API Writing Snapshot Tests For React Components With Jest
36. Introduction More detailed explanation on the headline. Should be about 2 - 5 sentences.
37. Introduction Help reader determine if article is relevant.
38. Example of a Good Introduction
39. Requirements Tell the reader the knowledge needed to follow along in the article. Be very specific here. State the technologies required. State the version needed
41. Explanation Step by step explanation of your topic Break your topic into smaller parts Group related material together Arrange information logically so that your reader will not be confused Move from simple to complex
42. Explanation Use visual cues Use illustrations Use code examples
43. Summary Give a summary of what you’ve discussed. Repeat important points for emphasis Add links to resources you found helpful Add links to resources if the reader needs more information
44. Tips on Writing 1. Keep it simple. Do not write ten sentences to explain a concept when two or three will do. 2. Do not assume that your reader understands the jargons you use. Explain when you can. 3. If your article is not a tutorial, do not make it too long. 4. Don’t write very long paragraphs.
45. Tips on Writing 5. Do not use images for code examples. Don’t do it!!! People need to be able to copy your code if they need it. 6. Embed your Codepen or JS code examples so that user can run it in the article. 7. Don’t make your user feel stupid. Avoid using words like ‘simply’, ‘just’. 8. Use a grammar editor like Grammarly, Hemmingway. 9. A little humour is good but don’t overdo it.
46. Code Review Important especially when for tutorials and when you have code examples. Have someone follow your tutorial step by step to make sure the code works
47. Grammar review Have someone review your grammar
48. Where to Publish Medium/Personal Blog Dev.to Scotch.io Codementor.io Medium.freecodecamp.org
49. Publish YAY!!!!!!!
51. What to expect Feedback - People will criticize, people will point out your mistakes. Accept it and make corrections when necessary. You’ll learn a lot from such feedback.
52. What to expect Growth - You’ll learn more, you’ll be more confident
53. Moving on Write regularly - as often as you can. Be consistent. Keep up with new tools or frameworks in your area of specialization. Build a brand of quality content.