As I try to wrap my mind around the requirements of one of my current projects, I find myself struggling with the fundamental paradigm of single source publishing.
Consider Project Godzilla, as I’ll call it. Project Godzilla involves an API that plugs in requests from a lot of different product lines, thus serving as a kind of master API for dozens of products. The total possible JSON submitted in the request is quite large, since it accommodates so many potential products. But each customer will only use a slice of the JSON. As a result, the delivery engineers want to give customers only that slice of the JSON that they will actually need to make requests.
Here’s an analogy. You’ve got a basket of fruit that you’re offering to people, but each person will only eat one piece of fruit from the basket, such as an apple, orange, or banana. You want to give each person only the documentation for the fruit they are consuming, not the documentation for all fruit in the basket.
There seem to be at least three separate models for tackling this kind of single-sourcing scenario.
A lot of the static site generating tools, from OxygenXML to help authoring tools to Jekyll and others would solve this problem by having you apply various tags to the different fruit, or rather to the different elements of JSON in the request. Then you run a build process that spits out a separate site for each product based on the tags you want to include or exclude.
Sounds good, right? Now you have 10 sites and you give the appropriate links to each person. Each person sees only the information that pertains to the product/fruit he or she is consuming.
But as you version the documentation and translate it as well as provide PDF and e-learning outputs, the number of sites grows, and after a year or so, you find yourself managing upwards of 100 plus independent site outputs. What’s wrong with this model?
Enter the rights-based login model. Rather than publishing a ton of different outputs, you apply conditions in your content that filter based on certain viewing rights in a CMS. Users log in to the CMS, and based on the rights associated with their profile, they see what they should see. The group with viewing rights for oranges just sees oranges, and so on.
This model is better because you have just one site rather than 100 separate ones to manage, but it still suffers from problems. Here are some challenges:
Enter another model: dynamic filtering. In the dynamic filtering model, the user chooses facets that allow him or her to dynamically filter the options and content available. You still have tags, but rather than implementing a rights-based approach that enforces what users can or can’t see, you allow users to select those rights and let the content filter automatically. Here are the problems with this approach:
Which is the right approach?
From a documentation perspective, they each come with challenges. However, after living in the first model for the past year and a half, I’m much more inclined to try out one of the other models — the single site with lots of filtering options, or a single database with rights-based views.
I’m curious to hear your experience with these various models for single-sourcing content.
Get new posts delivered straight to your inbox.
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.