Finished up the section on documentation processes (for now)
I finished up the documentation processes section in my API course that I've been adding to over the last couple of months. Here's a list of all the article in this section.
New API course article: Processes for changing internal doc culture
I added a new article in my API documentation course about processes for changing internal doc culture. One of the most influential aspects that will determine your experience as a technical writer is the company's documentation culture and environment. If you find yourself in an organization with a poor documentation culture, it can be difficult if not impossible to change it. Poor documentation culture/environments lead to a high turnover on doc teams, loss of motivation for existing writers (especially as their colleagues constantly leave, which increases the workload), and contributes to a downward spiral of tasks you can never quite get a handle on. In this topic, I outline six strategies you can implement to influence change in your company's documentation culture.
New API course article: Processes for external contributors
I added a new article to my API documentation course on processes for external contributors. One of the main advantages of a version-control-based system, especially using open-source technologies, is the promise of collaboration. Not just collaboration with your immediate team, but scaling beyond your team to also include other contributors within your organization and even contributors from the community. Many people embrace docs-as-code with the hope and expectation that many engineers will contribute to the docs. In this section, I cover processes to consider when external contributors (external to your team, not necessarily external to the company) write content.
Documentation templates and The Good Docs Project -- guest post by Ankita Tripathi
Documentation templates not only help teams align with consistent approaches in docs, templates help guide engineers, non-writers, or other roles in creating content, removing the intimidation of a blank page. A group of writers passionate about templates have been working together to create templates for a variety of documentation scenarios. This group's project is called The Good Docs Project. The project makes available templates for API overviews, quickstart guides, reference, how-to topics, discussions, tutorials, and more. The following is a guest post by Ankita Tripathi, a member of The Good Docs project, discussing the project and her motivations for getting involved.
The story behind Document360 -- podcast with founder Saravana Kumar
In a previous post, I explored how Document360, a new cloud-based documentation platform, handles API documentation scenarios. This time, I decided to record a podcast with Saravana Kumar, founder of Document360, to get the behind-the-scenes story about how Document360 came about, what's driving their fast pace of development, and their roadmap for the future.
Process for collecting feedback post-release (new article in API doc course)
I added a new article covering the process for collecting and addressing feedback post-release in my API doc course. Collecting feedback post-release involves a host of new challenges and processes, such as how to optimize your feedback form, how to account for random externally driven requests across your dev portal, how to process the feedback from incoming requests, and so on.
How does Document360 handle challenges with API documentation?
How does Document360 handle some of the tooling tasks common with API documentation? In this post, I look at some sample API doc sites using Document360 and look at how they handle aspects such as collaboration, GitHub integration, search/findability, versioning, OpenAPI integration, code-syntax highlighting, context-sensitive help, and developer portal architecture.
Write the Docs Podcast episode 32: Self-publishing and AsciiDoc, with Mehmed Pasic
Many tech writers are familiar with using AsciiDoc for documentation, but did you know that you can also create fiction and non-fiction books with AsciiDoc, publishing to popular digital formats such as EPUB or PDF, along with HTML? In this episode of the Write the Docs podcast, we chat with Mehmed Pasic from Manning Publications about self-publishing, AsciiDoc, collaborative workflows between authors and editors, trends in book publishing, the most popular devices for consuming content, book versus video formats for technical content, and more.
Processes for maintaining existing documentation (new article in API doc course)
As soon as new docs are published, docs begin a trajectory of decay. The natural progression of technology makes documentation outdated within a matter of months or years. New versions of web browsers, operating systems, supporting utilities and tools, etc., are released, and the whole technology landscape keeps moving forward, evolving, improving, and adjusting — all while documentation remains static. The more your documentation relies on third-party components, the faster it goes out of date. Most documentation efforts focus on creating *new* documentation, but what happens to all the *existing* documentation that is decaying? In this new article in my API doc course, I cover ways to maintain existing documentation to prevent it from rotting.
Developer experience (DevX) usability (new article in API doc course)
I added an article called 'Developer experience (DevX) usability' to my API doc course. Usability can be roughly divided into at least three different areas: (1) Usability with physical products, (2) Usability with code products, and (3) Usability with documentation. Few usability researchers venture into usability with code products because it’s much less clear how to assess the usability of code. But make no mistake, usability is just as much in play with code products for developers as with physical products or products with GUIs.
Does working outside with the world as your office actually work?
The other week I was trying to get a better grip on work-life balance. For me, the key challenge was that, without a commute and being at the office, there wasn't a clear separation between work and home. As the result, the two began to blend together. I spent a few weekends working off and on between family and football, and I felt like I needed to change things. To try to fix this and create a more firm separation between work and home, I decided to take my virtual office to a nearby park and work there all day, simulating being at the office. Then at 5 pm I planned to return home, hoping it would have the same effect as if I'd been at the office all day. It didn't go as planned, but not for reasons I thought.
Coffee and Content webinar recording: Treat Code Like Code; Treat Prose Like Prose
I recently participated in an upcoming Coffee and Content webinar called Treat Code Like Code; Treat Prose Like Prose on September 24, 2020, with Scott Abel and Casey Jordan. A recording of the video is now available.
New article in API course: Processes for reviewing documentation
Conducting a successful documentation review is challenging, especially with developer docs because the content is often highly technical and requires a lot of engineering input and review. At the same time, getting this engineering input and review doesn't come easy. In this new topic in my API course, I outline a tactical approach to conducting doc reviews for large projects.
On cultivating a garden while the world is crumbling around you
Last Monday was one of my lowest days of the pandemic. The wildfires burning up and down the west coast had made our air toxic, so I'd been indoors for the past four days. We'd already been at home all day because of the pandemic, but at least we could go for hikes and bike rides and walks. Now we just had the surrounding walls of our home.
SmartBear's 2020 API report finds 'Accurate and detailed documentation' to be second-most important characteristic of APIs
SmartBear recently published its 2020 The State of API report, which collected responses to 52 questions from 3,500+ respondents. Reading this report will make any technical writer feel like he or she has an important role with API docs. However, the report also notes that 'API documentation represents big opportunity for improvement,' which I think suggests that many existing processes for documentation in the software are kind of broken.