Robert Delwood, the lead API Documentation Writer at iManage, joins the Knowledgebase Ninja Podcast to share the thirty-three rules of API documentation, the fundamentals of producing API documents, and the challenges of creating high-quality technical documents.
Key facts
- Robert’s LinkedIn
- iManage’s website
- Robert has a MA in CIS/MIS and a BA in Journalism and Business Administration
- Robert is currently working as the lead API Documentation Writer at iManage
- Robert has been serving the technical writing niche for over 5 years
Kay takeaways
- Robert began programming in 6th grade and later pursued journalism and business administration in high school
- Robert believes that his exposure and self-practice in programming provide him with an edge in creating high-quality technical documentation. “Understanding of backend and programing helps you deliver better technical content and help in explaining the concepts to the targeted audiences”
- Robert advises programmer writers to focus on meeting user expectations rather than only fulfilling the requirements
- Robert believes that API documentation is more of an art than science. There are pre-defined API documentation reference guides, but it’s advisable to choose a style that works best for you when communicating new ideas and concepts to consumers. The bottom line of a technical document is to help users digest technical information in the most simple manner
- The most important factors for quality documentation are meeting audience expectations, the call name, and having defined parameters. You can start out in a conventional manner; your personal style of technical documentation should evolve through the course of a document. Examples include code snippets, starting guides, and how-tos, to name a few. Some programmer writers produce entire applications in order to showcase the calls and the interaction of the calls. A “call site of a function or subroutine” is the location (line of code), where the function is or is not called, through dynamic dispatch. A call site is where zero or more arguments are passed to the function, and zero or more return values are received
- Robert follows a strict regimen constituting thirty-three rules for documentation. One of them is that you document it for yourself. Explain a new concept to yourself first, then teach the company product to develop it. If you don’t understand something – stop and repeat
- Robert shares that learning to code isn’t mandatory to enter into the technical writing industry. However, a technical writer can deliver better documents when they can feel the code or technical concept in action. API documentation is all about quoting technical examples, and writers should have technical soundness to explain concepts in examples
- Robert shares his knowledge bank on Medium and Reddit regularly. He believes that putting up an article online enables him to access it conveniently
- Robert believes that technical documentation tools need improvements. Before Open-API, there were no standards, both code and documentation were rarely synchronized. The YAML tool is a great addition to the community
- Robert believes that the world needs API documentation writers, and encourages people to establish a career in API documentation
- Robert’s biggest influence
Robert considers formal and informal conversations with developers as the best form of learning. He says that feedback from developers enabled him to understand concepts better.
What documentation related advice would Robert give to his 20-year-old self?
Robert’s advice to his 20-year-old self would be to “learn any sort of technical skills, be it programming language, Windows OS or Linux OS. This will help you flourish in a technical writing career.”
Robert’s favourite documentation related resources
Subscribe to the Knowledgebase Ninjas
Quote:
–