Adobe Robohelp

Get new posts delivered straight to your inbox.

Subscriber count: 3,725

Stitcher radio

follow us in feedly

Want more tech comm blogs to follow? See my Tech Comm Collection of Blogs on Feedly.

Adobe FrameMaker

Updating a single page versus updating the documentation as a whole

Dec 14, 2016 • general

This past week I made some contributions to the Jekyll documentation, and in making the pull requests, I realized why technical writing is often so difficult. Making a request to one documentation topic often requires you to adjust other topics as well. So often we place the bar for contribution at whether someone can write. In reality, it's not just whether someone can construct clear, grammatically correct sentences. It's whether the person can integrate the information into a larger documentation set.

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.

follow us in feedly

Get new posts delivered straight to your inbox.

Subscriber count: 3,725

About Tom Johnson

Tom Johnson

I'm a technical writer based in the California San Francisco Bay area. Topics I write about on this blog include technical writing, authoring and publishing tools, API documentation, tech comm trends, visual communication, technical writing career advice, information architecture and findability, developer documentation, and more. If you're a professional or aspiring technical writer, be sure to subscribe to email updates using the form above. You can learn more about me here.