Newsletter: Docs-as-ecosystem, structure in WordPress, identity crisis, and pencils
- Docs-as-ecosystem: The community approach to engineering documentation, by Alejandra Quetzalli
- Constructing Structured Content on WordPress: Emerging Paradigms in Web Content Management, by Daniel Carter
- Podcast: 57: The New Generation of Tech Writers with Carlos Evia and Rebekka Andersen – Content Components with Patrick Bosek
- Not your typical technical writing course (Sponsor)
- I, Pencil, by Leonard Read
Docs-as-ecosystem: The community approach to engineering documentation, by Alejandra Quetzalli
Alejandra Quetzalli, who works in open source software and API tooling development, has a forthcoming book from Apress called Docs-as-ecosystem: The community approach to engineering documentation. In the book, Quetzalli introduces a new metaphor to guide documentation’s development: “the ecosystem.” The ecosystem refers to the diverse, multi-person environment needed for feedback and input to shape and grow documentation.
Quetzalli says the docs-as-code metaphor focuses too much on tooling and engineering workflows without acknowledging the larger ecosystem of user input and interactive processes needed for documentation to thrive: “The docs-as-ecosystem model proposes a different way of thinking about technical documentation; it recognizes technical documentation is not just a product but an ongoing conversation between diverse documentation creators (contributors) and the community.”
I haven’t read the book yet (it’s available for pre-order only now), but it’s interesting to see the docs-as-code metaphor de-emphasized like this. It seems that docs-as-code model evokes a kind of lone writer working in isolation (like a programmer in a basement), separated from the large number of users, product teams, open source communities, and other stakeholders needed for docs to thrive.
Constructing Structured Content on WordPress: Emerging Paradigms in Web Content Management, by Daniel Carter
Communication Design Quarterly, Issue 11, vol 1, March 2023
Daniel Carter, a professor at Texas State University, examines how attempts at structure in WordPress, a web-based content management system (WCMS), provide a bridge to other structured authoring learning and strategies. The WordPress editor has evolved from a single WYSIWYG blob to a more section-based page builder (the Gutenberg editor) that involves dragging in blocks for different content types (quotes, images, headings, paragraphs, etc.). Additionally, third-party plugins (such as Advanced Custom Fields) allow authors to create custom metadata fields and reusable content blocks for additional structure.
Carter says these structures are mostly single-page structures that contrast with the content chunks in component content management systems (CCMSs) that are intended for re-use across multiple pages or outputs. Overall, WordPress provides an avenue for thinking about how to apply structured authoring concepts to content within a popular, real-world authoring tool.
Podcast: 57: The New Generation of Tech Writers with Carlos Evia and Rebekka Andersen – Content Components with Patrick Bosek
In this podcast, professors Carlos Evia and Rebekka Andersen explain why the next generation of content professionals is undergoing an identity crisis. Tech comm program names are inconsistent (for example, Professional Writing, Technical Communication, Writing and Rhetoric, etc.). The organizational groupings are also varied (some programs are in the English department, others in Engineering, others in Communication, etc.).
Most importantly, though, there’s no longer a coherent focus that ties the discipline together. It used to be that most everyone in tech comm focused primarily on producing user manuals. With the user manual paradigm gone, the discipline fragmented into many different areas of focus, from UX writing to API docs to content strategy and more. As a result, the tech writers coming of age today lack a common identity. The term “tech comm” no longer encompasses what they do. This identity crisis makes it difficult for academics to prepare students for their many post-college paths. These professors feel “Content Professional” might be a better term that suits the diversity of the role.
Not your typical technical writing course (Sponsor)
Universities and other institutions teach by copying available material in existing courses and stuffing your head with information that may or may not apply to get started as a technical writer.
Jump School focuses on exercising knowledge — doing exercises, creating documents, and building a portfolio.
These courses are “lean” and not full of theoretical or abstract knowledge so most members who earn a certificate are actively working in the industry within a few months.
Use code April100 when signing up for the Jump School and save $100 off the course price. (Offer good only for April.)
I, Pencil, by Leonard Read
This classic and beloved article is an early example of end-to-end systems thinking, focused on a seemingly ordinary, non-technical object: a pencil. Read describes the development processes and stages required to create a pencil, arguing not only that most people aren’t aware of how pencils are made, but that the supporting technologies behind the development processes are equally opaque. He springboards into more philosophical ideas to argue that there isn’t a single planner but rather an invisible hand that leads to pencil abundance. Putting the philosophy aside, the article highlights the complexities of documenting a product end-to-end and the delight that unfolds when you illuminate this horizontal trajectory.
About Tom Johnson
I'm an API technical writer based in the Seattle area. On this blog, I write about topics related to technical writing and communication — such as software documentation, API documentation, AI, information architecture, content strategy, writing processes, plain language, tech comm careers, and more. Check out my API documentation course if you're looking for more info about documenting APIs. Or see my posts on AI and AI course section for more on the latest in AI and tech comm.
If you're a technical writer and want to keep on top of the latest trends in the tech comm, be sure to subscribe to email updates below. You can also learn more about me or contact me. Finally, note that the opinions I express on my blog are my own points of view, not that of my employer.