The following is a guest post by Edgar Allen Poe. Poe completed many works of both fiction and nonfiction in his life, including 'The Raven', 'The Fall of the House of Usher', 'Eureka', and most famously, the 'Tell-Tale Heart'. Many are unaware that one of Poe's first jobs was as a technical writer. In this post, he explains some deep conflicts and challenges he had on one project, and how he overcame the challenges.
In the debate between being a specialist or generalist, there's also a third option: developing technical acuity. A person with a high degree of technical acuity has the technical mindset needed to understand and solve problems across a variety of technical domains. Given the ever growing number of technologies, developing technical acuity can be more advantageous, especially in technical writing contexts since technical writers work with a lot of different technologies.
In this Write the Docs Podcast episode, we chat with Mark Baker about structured writing, specifically focusing on his new book Structured Writing: Rhetoric and Process. After introducing and defining structured writing, Mark explains the four domains you can add structure: media, document, subject, and management domains. He explains the advantages of working with structure in the subject domain, and why mixing structure across subject and document domains can be inefficient. We also chat about how structured writing connects with SEO and microformats on the semantic web, the limits of structure in Markdown formats, how to implement structure in linking, and more.
Last week during an internal writers conference at Amazon, Carla Johnson (co-author of the Experiences: 7th Era of Marketing and other books) gave a workshop that ostensibly was about how to create more persuasive pitches for change within an organization. But what resonated with me a bit more was the novel technique for brainstorming by transposing categories of experience, which despite my background in literature and writing, I had never encountered.
When giving an hour long presentation, about 15 slides is ideal. Although having fewer slides might make you panic about possibly forgetting what you want to say, in reality fewer slides gives you more flexibility to narrate your idea journey in a dynamic way. If you have too many slides, it locks you into a fixed, rigid structure that can actually make presenting harder. Additionally, a good essay is often the foundation for a good presentation because many of the rhetorical elements of an essay (the introduction, thesis, evidence, argument, etc.) are reflected in presentations as well.
Trends in technical communication can be hard to decipher, even when looking at data. But one underlying trend is that technology seems to be getting more specialized and complex. This trend toward specialization is driving up the value of technical knowledge, making it more prized than writing skills. To handle the complexity, technical writers must play increasingly collaborative roles with engineers to create documentation.
Technical writing jobs have shifted more from the end-user domain to the developer domain. This creates challenges because most technical writers are generalists, not specialists, when it comes to technology they document. In these specialist contexts, technical writers can add value by focusing on authoring/publishing processes and tools, knowledge of the user experience, and information usability.
Thanks to UX design, technology is becoming a simpler experience for end-users; however, the code is becoming more complex behind the scenes. As a result, more technical writing jobs are transitioning to the areas of complexity in the developer domain. Because content in the developer domain is so technical and specialized, many developers are collaborating and assisting with the documentation. As developers get involved in docs, they usually adopt docs-as-code tools, writing in simpler Markdown files.
When specialists write docs, they tend to stick with simple formats and tools. As a result, incorporating structure or writing to specifications often gets overlooked. This is one area where technical writers can add value.
Specialists often lack user feedback to guide and inform their decisions. This is an area that technical writers can provide value, especially in helping identify problem areas in the user experience.
When specialists write, they often neglect principles of information usability that can make their content more easily consumable by readers. Some of these principles include letting users switch between macro and micro views, making information discoverable as the user needs it, ensuring information harmony in the larger landscape, and reducing and distilling vast information down to its essence.
My discussion of information usability principles continues here. Some additional information usability principles include conforming to the patterns and expectations of the genre and schemas, reducing the complexity of technical language, and iterating and incrementing on content following an agile approach.
Wrapping up this series, the conclusion recaps the argument highlights and information usability principles.
The latest Cherryleaf podcast lists the available tech comm podcasts and how to get started with your own podcast. I created a short survey about podcasts to gather some feedback about your listening habits and preferences.
Showing users the 'Pages at a glance' when they click a folder title in a sidebar can help users get a quick understanding of the whole without slogging through the details of each page. The first two sentences of a topic should encapsulate the point of the whole topic is a condensed and informative way.
