Write the Docs Podcast episode 8: Stack Overflow's Documentation Failure and Open Source Challenges
In this Write the Docs Podcast episode, we're joined by Beth Aitman to talk about what happened with the Stack Overflow Documentation Beta. What did Stack Overflow try to do with documentation, and why did they abandon the effort? Why did their effort to crowdsource docs fail but succeed so well with forums and niche content? Additionally, we discuss the difficulties of creating good documentation with open source projects. A recent survey found that incomplete or outdated documentation is the number one issue with open source projects. Why? What makes it so difficult to create documentation on an open source project?
Why Stack Overflow's Documentation effort failed -- a few thoughts from a technical writer's perspective
Stack Overflow, mostly known as a forum for answering niche software questions, recently tried to launch a Documentation component to their site. The goal of Documentation was to 'do for Documentation what we did for Q&A'. In other words, provide substantial, valuable information that could be the go-to source for tech docs instead of just one-off answers around niche topics. However, the effort failed and now Stack Overflow is sunsetting their Documentation.
Tech docs and Agile: Alternatives to integrating into engineering Scrums (Part 2)
This is part two in a series on Agile and tech docs. In the previous post, I outlined challenges in integrating into engineering Scrum teams. Some alternatives to Scrum include Kanban, Extreme programming, Waterfall, and various productivity methodologies. The most compelling solution, to me, seems to be to form your own documentation-focused Scrum. This allows you to keep with the same project management approach and language in the company, while also allowing you to avoid the pitfalls previously described with integrating into an engineering Scrum. Even so, there's not an extremely compelling reason for docs to adopt Scrum, so its main aid might be to give you a disciplined approach to your doc work.
Tech docs and Agile: Problems with integrating tech writers into engineering Scrums (Part 1)
Although it seems like documentation should be treated like other features worked on by a Scrum team, frequently it is not. When tech writers try to integrate into engineering Scrum teams, they usually run into a host of challenges. These challenges stem mainly from floating across multiple projects. Often doc tasks aren't assigned points or grouped in with other tasks in a real sprint, nor are tech writers co-located with project teams. This is a two-part post. In this first part, I outline problems for tech writers integrating into Scrum teams. In part 2, I explore solutions.
Why simple language isn't so simple: the struggle to create plain language in documentation
Although you can adjust your content's style to be simpler and more readable, technical documentation introduces many new terms and concepts for readers to learn. Many readers who don't already understand the discourse community may find this language impenetrable. Glossaries and inline tooltips can potentially help novice users, but there's no easy solution for simplifying your language for both novice and expert users.
When the pain of ignorance exceeds the pain of learning
Users turn to documentation when the pain of their ignorance exceeds the pain of learning. Unfortunately, this is the worst state of mind to try to learn anything in. To address this impatient state of mind, we need to write documentation in simpler, easier to digest ways. Task-based documentation gets us part way there. But the varying starting points, unique pathway needs, and messy branching complicate the promised simple linear nature of steps. Overall, we need to increase the simplicity factor in our docs much more than we generally do.
Transparency in documentation: dealing with limits about what you can and cannot say
Although traditionally as a technical writer you don't run into too many ethical scenarios for docs, sometimes you have situations where your ability to be transparent about a system's limitations gets curtailed by marketing or product management. It can be frustrating to have your documentation filtered like this, but you can take comfort knowing that, given the decentralized nature of information on the web, where any user can post information in forums, blogs, and other sites, the information filtered out of your docs will eventually be published online (it just might not be published by you).
Write the Docs Podcast episode 7: Let The Robots Do The Work
In this podcast, we first explore the flourishing community of technical writers in Poland, discussing why the tech writing scene in Krakow is taking off so quickly and what trends this young tech writing community is embracing. We're joined by special guest Pawel Kowaluk, a Polish tech writer who runs SOAP (a tech comm conference based in Poland). We also talk about automation and robot takeovers of tech writing jobs. How are machine-assisted technologies enhancing or displacing technical writers and their work? Given the increase in automation, is tool expertise becoming more or less essential to thrive as a technical writer?
Circle review -- How to manage your kids' access to Internet devices
With four kids and a house full of devices, it can be pretty hard to wrangle devices from kids' hands and shut off Internet time. In the past, I tried putting all the kids' devices onto a guest network and all my devices onto a main network. When I wanted to shut off the kids' access to the Internet, I would log into my router and shut off the guest network. Now I have a new approach that seems to work much better.
My second-chance points strategy with documentation
In addition to being a technical writer, I also play basketball. I might spend more time playing basketball, in fact, than I do writing on this blog. I never played college ball, but I love playing pickup basketball several times a week at various courts. Now that NBA season recently finished, I figure it may be relevant to expound a bit on a pet theory of mine about how to win at pickup basketball games, and how that same strategy might apply to winning at documentation.
The problem with Frequently Asked Questions (FAQs) in documentation
Many tech writers have a heavy disdain for Frequently Asked Questions (FAQs) in documentation. At first this disdain seemed a bit unfounded and elitist to me, but now, after a recent project, I'm starting to understand the reasons for the disdain. All too often the FAQ format is abused by non-writers who want an easy way to write. The list of random questions grows with each incoming question until it's a ridiculous hodgepodge of information thrown together, with no larger story or narrative.
Recording of my WTD Portland 2017 presentation on Building navigation for your doc site -- 5 best practices
Here's the recording of the presentation I gave at the Write the Docs 2017 Portland conference. The presentation explores best practices for doc navigation, including principles such as hierarchy, modularity, progressive disclosure, entry point, and wayfinding. The presentation is about 20 minutes long, and you can either watch a video or listen to audio. Other WTD presentation recordings are also available.
Write the Docs Podcast episode 6: Metadata and UI copy
In episode 6, we explore the role of metadata in documentation and how it can be used to classify topics and assist in the discoverability of information. We’re joined by special guest Eva Jackolis who explains a strategy for metadata used in German mechanical engineering documentation. We also discuss involving tech writers in UX copy and the challenges inherent in influencing UI copy, product naming, and working with UX designers and product teams.
Limits to the idea of treating docs as code
If there's been a theme for the past year in tech comm, it's to treat docs like code. Most people get behind this idea with a great amount of enthusiasm. And yet, in many ways, docs are not entirely like code. You can make processes a lot more complicated if you push the the docs-as-code idea to the limits. Docs differ significantly from code when it comes to release frequency, release complexity, review processes, and company support.
How big should your documentation repo be?