This is the seventh post in a twenty-post series blogging challenge. The challenge is to answer a question that somebody has asked you online or in-person.
I was asked in a job interview recently: How would I go about creating technical documentation for a product? Read on below to find out how I might approach a technical documentation or curriculum design project.
First, I would get to know my audience. Where is my audience posting their thoughts? Are they posting on Hacker News or Reddit; or are they reading white papers? I need to find my audience and get a picture of what’s important to them, what problems they’re having, and what kind of language they’re using to describe the tool or product. What’s they’re overall impression and what information is currently prominent about my product? These questions will give me an accurate description of who I should write for.
Next, I would learn the tool myself and document my steps starting with how to complete basic functions with the tool or product. How do they get started with the install and a basic project? If developer’s notes are available, I will integrate them into my outlined understanding of the tool. If there’s current documentation, it can be remixed or used to build new, better documentation. Sometimes this step requires some trial and error to learn how a new user would organically use a new tool.
Once I have a good understanding of the basics of a tool and an outline of the documentation started, I would then take screenshots and create images where visual support to understanding is needed. Sometimes it’s easier to complete the outline of the major functions and the instructions and then come back at the end to take screenshots when you fully understand what you’re looking at.
Lots of code on this screen. Image by Tudor Baciu.
Lastly, I would finalize the documentation and request feedback from any stakeholders available to review the documentation, ensuring its accuracy and efficiency to reaching the stated goals. I would verify the consistency of word usage, directional word usage, headings, formatting, and accessibility best practices applied. The documentation would then be deployed externally and I would appreciate feedback from any user utilizing the documentation.
Technical documentation, especially for a tool that will have updates and new features in the future, is a flexible, growing foundation for learning a product or removing headaches when a problem presents itself: A communication of solutions and pathways.
#amberclee #20postchallenge
