Can you collaborate on doc projects in Git with other writers?
A reader recently asked how to collaborate with Git with other writers. He said they found it hard to develop a Git workflow that allowed them to work on content together and wondered if another approach might be more suitable.
New topic in API course: Five strategies for documenting code
Previous articles I've shared on documenting code introduced the complexity of the challenge. In this article, I expand on five different techniques writers take in documenting their code, including the Lego approach, the Nautilus approach, juxtaposed columns, and more. In particular, I expand on why describing the finalized code might not be so instructive for users, and why it's nearly impossible for writers to decompile the developer's logic that led to the finalized code anyway. See Five strategies for documenting code.
New topic in API course: Research on documenting code
I added another topic to the Documenting Code section in my API documentation course. This new topic is called Research on documenting code and summarizes/discusses two academic articles on documenting code.
New topic in API course: Why documenting code is so difficult
I recently added a new section in my API documentation course on documenting code. This is an entire section that I'm building out with about 7-8 topics. The introduction is called Why documenting code is so difficult.
WTD Episode 22: Managing multiple doc projects across Git repositories, with Giles Gaskell
In episode 22 of the Write the Docs podcast, Giles Gaskell from Squiz in Australia joins us to talk about managing multiple doc projects across Git repositories through Antora. Giles explains how to establish processes such that updating documentation becomes part of the definition of done, how to manage build process across multiple Gitlab repositories, strategies for distributing doc work across engineers through templates, how to scale workloads when you're the lone technical writer in the company, times when dogfooding your own product for docs makes sense and when it does not, pros and cons of Asciidoc versus Markdown, and more docs-as-code topics.
Single-sourcing data into table templates in Jekyll
Jekyll lets you separate out your data from your presentation layer. You can store your data in a YAML file and then populate the data into templates as desired, passing parameters into includes. In this post, I describe my process for creating tables where I might re-use the same definitions in various places in the docs.
Upcoming API Documentation Workshop in Mountain View, Calif., on August 30, 2019
I'm giving an API Documentation Workshop in Mountain View, California, on August 30, 2019. Although I've given more than a dozen API documentation workshops at various conferences over the past several years, this one is different. For this workshop, I'm organizing it myself. You can register on Eventbrite.
Every project is a monster you battle and slay
Some tech comm projects are like monsters we battle. Is there any truth to the idea that it takes a monster to kill a monster?
If I am learning to write developer documentation, should GraphQL be on my radar? -- guest post by Casey Armstrong
GraphQL, a query language developed by Facebook, is an alternative to REST that is rising in popularity. Exactly how does GraphQL differ from REST, and what documentation strategies and conventions should you follow when documenting a GraphQL project? In this guest post, Casey Armstrong explores GraphQL — the query language, its use cases, its tools, what developers need from its docs, and whether GraphQL is worth learning. Overall, Casey argues that learning GraphQL is a great way to specialize and stand out as a technical writer, but the technology is not talked about in the tech comm/API writing community as much as it is in the developer community.
If the current trend in software development is independent agile teams, does enterprise content strategy have any chance of realistic adoption?
Agile seems to favor independent, autonomous teams. In contrast, enterprise content looks to harmonize content across multiple teams and boundaries. In a current model where agile trends dominate, how do you reconcile larger needs for enterprise content strategy?
Recording of Tech Comm Trends Presentation (STC Puget Sound chapter)
I recently gave a presentation on technical communication trends to the STC Puget Sound Chapter in Seattle, Washington, on May 21, 2019. This is one of the better presentations on trends I've given and culminates a lot of research and other iterations on this topic during the past year. You can view a recording of the presentation, check out the slides, grab the audio file, and see other details here.
ClickHelp -- a flexible online platform for authoring and publishing technical documentation
Let's say you need to create and publish technical documentation. Maybe you have a team of distributed authors, and you need all the robustness of an advanced tech doc solution, but you don't want to create your own version from scratch. (I've argued in numerous posts that creating your own tools from scratch can require a lot of time and hidden expenses.) Enter ClickHelp. ClickHelp is a flexible, online help authoring solution that offers an impressive number of features, from context-sensitive help to built-in metrics, content re-use, PDF export, full-text search, password protection, full review cycles, readability analysis, and more. In this post, I'll provide brief descriptions and screenshots as we browse through the various features ClickHelp offers.
My documentation project plan template
In this post I share my documentation project plan template. This is designed for project managers to complete. Having all these details present helps you scope projects and recall all needed details if you have to de-prioritize the project for a while.
How to avoid inefficiencies even with context switching
When you switch focus from one project to another with higher priority, this context switching can lead to a lot of inefficiencies. However, if you take time to review or work on the de-prioritized projects even just a little each day, then according to the Forgetting Curve, you'll be more likely to retain the needed context. When you do fully switch back to the project, you won't have to start over.
Reader question: Am I specializing too much by limiting my focus to docs only?
A reader asks whether he should be focusing not only on writing good developer docs but also building out doc portals and marketing material — in other words, being more of a 'full-stack' technical writer. This question taps into the dilemma between being a specialist or generalist.
subscribe via RSS