Updating a single page versus updating the documentation as a whole
Documentation topics are interconnected
Although at times documentation of a new feature simply involves adding a new page, more often the new feature affects a getting started section, a sample app, other pages that reference the feature, tutorials, code samples, and more. Changing one topic can set off a cascade of other needed edits across the entire documentation set.
As such, it may be particularly difficult for people with a narrow focus to contribute holistically to documentation. For example, developers usually work on one slice of the software pie. They dive deep into coding a specific feature.
Developers may write up coherent documentation on a single page describing how that feature works, but integrating that information into the larger documentation set requires them to be familiar with all the other parts of the documentation, with all the other existing features, the styles and conventions used in other areas, and more. They have to know what other content exists, and how their contribution fits into that content.
Developers have rarely read all the documentation for a product, so the task of contributing in a holistic way to the documentation becomes more difficult and time-consuming. The required analysis and integration into larger information structures requires a wider, more encompassing view into documentation. It requires someone who has a broader (though probably shallower) knowledge of all topic areas rather than a deeper (but narrower) knowledge.
As the trend toward more specialized knowledge increases, we risk creating silos within the same documentation set. By silos, I mean standalone pieces of information that are complete unto themselves, but likely redundant, overlapping, and inconsistent when viewed as a whole against other documentation topics.
Github’s model for contributing
On Github, a common model for soliciting contributions from others is to add an “Edit in Github” button on the page. This button takes the user to the source in Github that needs to be updated. While I think this simplicity is worthwhile, it also doesn’t acknowledge the more challenging task of updating the documentation as a whole instead of updating just one page. Documentation isn’t an island — it’s all interconnected.
Fortunately, with the “Edit in Github” button, you’re not limited to just editing a single page. Clicking the Edit in Github button prompts you to fork the repo and create a new branch (called “patch-1” by default). After making this fork, you can then clone your repo locally (specifically cloning the patch-1 branch), make additional edits on multiple pages against that patch-1 branch, and then submit all the edits in your branch as a pull request.
(For an introduction to the Git pull request workflow, see this presentation by Rhonda Glennon: Github for Documentation.)
The problem is that reviewers who see lots of edits across many different files may feel overwhelmed in processing the pull request, because now they need that all-encompassing view of the doc set as a whole to evaluate the changes. It’s much easier to break apart the pull requests into separate requests so that the changes can be evaluated in smaller chunks — that is, assuming the changes aren’t all part of one larger update that ripples across the docs.
In summary, it’s not just an ability to write that matters when it comes to contributing to documentation. It’s the ability to integrate information into a larger, coherent whole that makes the role of technical writing unique, valuable, and challenging.
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.