Many companies discover the great resource of customer facing documentation. Quickly they run into the conundrum of how their preexisting docs can be scaled to account for larger doc sets and more writers.
Tools like Zendesk enable customer facing documentation and are great for single source operations. They might build on commit, lack versioning, and have no reuse ability.
With the exciting prospect of publishing custom configurations and APIs, dev teams come to find that they can develop ad nauseam and provide instructions for accomplishing features that would otherwise never be exposed.
This requires configuration of the documentation tools in a similar constellation of possibilities. If you want it, it very likely can be done.
How do you start though?
I talked with one company that recently scaled their tools and they said it’s not easy, but it’s worth it.
It’s going to require more personnel than originally planned.
There are a myriad of specializations in technical writing, but your going to need a particular type at the start. This technical writer is a big picture thinker. They’re your content strategist and information architect.
This person is going to immediately see the breakdown of information and begin organizing it into smaller units. They’re making connections left and right and planning how the documentation will be structured into posts as well as which types of multimedia is necessary to drive the point. They’ll use best practices and research to discover how the end user navigates through the docs and provide strategies to obtain consistency across documentation.
A content strategist may do the following too, but it may also fall into the hands of writer #2.
To have a cohesive product, the doc team needs to standardize common terms, define voice and tone, and ensure the tooling is properly utilized. Writer #2 may be a content strategist, editor, or the owner of the documentation of a particular product.
This information needs to be available across the organization with internal docs like SharePoint, and has to be a living doc that is constantly addressed and reinforced. It’s a good idea to verify style guides with dev teams, PMs, and other stakeholders like UX design. For more information on style guides, see my CIDM article.
You need a non writer too.
There’s a big difference between Zendesk and DITA applications like Oxygen, Ixiasoft, Madcap Flare, etc. These are highly customizable, structured authoring tools. They’re going to require an engineer to set up and maintain.
These tools enable concurrent development by just about endless amounts of writers with version controls to resolve conflicts. These writers are able to create a repository of single truth and reuse the content in multiple locations, editing the information from the single truth or create brand new content fit into an existing or new architecture. Keys can be created to change all cases of product or feature names at once. There’s a lot of really cool functionality.
These tools require additional tools to build and publish the content, which fall within the purview of an engineer. Some of these tools are integrated development environments like Eclipse, Palio, or related GitHub.
Writers new to these tools will greatly benefit from internal documentation on the usage of these tools, as well as reference for seasoned writers.
While changes to a Zendesk article post immediately, perhaps giving the expectation that content can be cranked out quickly, these scaling tools should have the expectation of coinciding with scheduled builds and official releases. Tooling needs to be phased in and adjusted by the tooling engineer. It’s also recommended to maintain a Slack or Teams channel to communicate on tooling status, issues, and troubleshooting.
By implementing customer facing structured authoring with a content strategist and engineer, a great source is made available to increase adoption and retention of products. Customer support cases can also be incorporated into the docs as well as the smaller customizations. The content can reinforce branding and serve as an additional tool for decision making. Sounds pretty good!
Hopefully this brief overview provides some clarity on the process. Let me know if you have questions and we can set up a time to chat!
Double Yew! 