The document discusses the essential aspects of technical writing, emphasizing the need for clarity, usability, and consistency in documentation. It outlines a process for creating effective documentation and highlights best practices, such as using active voice and clear terminology. Additionally, it stresses the importance of understanding the target audience and adhering to a style guide for uniformity.

1. Put the “technical”
in technical writing
- Hridyesh Singh Bisht

2. Hello, I am currently working as a technical writer
at OutSystems and contributing to AsycnAPI as
part of GSOD ‘23.
● www.linkedin.com/in/hridyesh-bisht
● https://twitter.com/hridyesh_bisht
● https://programmerprodigy.code.blog

3. What is
technical
writing

4. If you’ve ever struggled with poorly written instructions and
thought, “I could write better instructions than that!”
We rely on tech writers nearly every day. When we follow the
instructions to install a program into a PC or when we are setting
up a new phone.

5. How to
write great
docs

6. For documentation to be considered good, it should
possess certain attributes, regardless of the intended
user.
● Correct
● Complete
● Usable
● Clear
● Consistent

7. What does usability mean?
● The user is able to find information quickly.
● Instructions are clear and easy to follow.
● Instructions work as described.
● Users can find their place quickly when coming
back to it
What does clarity mean?
● Eliminate unnecessary words
● Use short words and short sentences.

8. Understand the
audience

9. You create a persona (a fictitious version of a user type) that
describes your target user and ask the following questions:
● What is the user’s goal?
● How often will the user refer to the documentation?
● What problems might the user encounter?
● How technical is the user?

10. Process

11. Every document requires following steps
1. Gather information
2. Plan content
3. Write
○ Outline
4. Verify
○ Review
5. Redo

12. A sample documentation plan would be
● Name of the deliverable
● What needs to be done
● Who is doing the work
● Reviewers
● Milestones and their expected dates
○ Date you need MVP
○ Date you need reviewer comments back
○ Final handoff

13. Deliverables

14. There are many decisions to make about how you present
documentation content. These decisions depend on
● what your users need to know
● how they will use the documentation
● how much time you have to work on the project
● how many different deliverables are produced from the same
content

15. Style Guide

16. Without a style guide, writers can, and will, choose any way they like
to treat capitalization, punctuation, and even spelling.
Is there more than one right way to do things? Of course. And it
usually doesn’t matter which right way you select, as long as you,
and your fellow technical writers, pick one and follow it consistently.
That can sometimes be hard, because we all have our favorite ways
of doing things.

17. Best Practices

18. Some best practices every technical writer should know:
● Use active, not passive voice.
● Use bullet lists to emphasize points and break up content.
● Chunk information into logical groups.
● Use clear and short words and phrases.
● Be consistent in your terminology.
● KISS or Keep It Simple.
● Avoid negatives.
● Stay in present.
● Use gender neutral language.

19. Questions ?