gd2md-html is a Google Docs add-on that will convert your Google Doc content into either Markdown or HTML. This tool provides a much-needed converter that enables you to use Google Docs as a platform for content development without manually reformatting the content when you're ready to publish it in another system.
Although technical writers champion plain language, embracing plain language for many years can cripple your ability to use more eloquent language, like that of a literary author or essayist. There isn't much room for literary play or playful tones in technical documentation. Following the rules of simple language has distorted my ability to read anything that blatantly violates those rules without questioning the author's word choice and sentence construction. Sometimes I feel that simple language has removed my ability to delight more in language and to express myself in more articulate, interesting ways.
In this episode of the Write the Docs podcast, we're joined by Ellis Pratt from Cherryleaf to talk about chatbots in documentation. What are chatbots, and how can you incorporate them in your docs to enhance the user experience? Are chatbots the next evolution of wizards? What are some examples of successful chatbots? How does one get started using chatbots in documentation? Are there chatbot services you can leverage inexpensively to try them out? These are some of the questions explored in this podcast.
This past week I had some good discussions with developers about the right directions in our doc-as-code project at work. I say good discussions, but actually they were challenging. The outcome led me to realize more details about embracing docs as code. The more you treat docs as code, the more you may have to set aside some common tech writer models of handling content and instead embrace the software code workflows entirely. Some of these principles include storing only source code in repositories, building from a build management system, and reducing build pipelines to work with 1 or 2 larger repositories only.
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?
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.
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.
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.
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.
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.
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).
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?
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.
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.
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.
