How do I maintain effective documentation for different audiences while avoiding duplication?

Question

I need to maintain documentation of the same system for different audiences. How do I avoid duplication while still being effective?

I have a publicly-available API, and I also have internal documentation of algorithms that are not meant to be shared publicly. There is also both high-level (overview, conceptual) material and deep details. I'm looking for standard ways to effectively tie them together so disconnects between the two are at least highly visible, without writing custom mechanisms to do so for each project.

Historically my organization has used Doxygen only for low-level design details, but we still have a lot of redundant documentation due to regulatory paperwork... It can be cumbersome to say the least. I know Doxygen provides for public/private tags but I'd like to have further ways of tagging things (high-level, low-level, operational, tool user guide, api user guide, regulatory compliance, etc...)

Answer 1

I think this depends on the tools you're using to create the documentation. Doxygen has some manual commands you can use for conditions: http://www.doxygen.nl/manual/commands.html

In most structured authoring environments, there are also ways to do this. My expertise is with DITA and in DITA you can use conditional processing attributes to tag content for different audiences, then filter out the tagged content when you're publishing. You can tag content at a high level, such as an entire topic, or more granularly, such as a step in a task or a paragraph or code block. In DITA, you can apply multiple conditional processing attributes for different purposes using standard or custom DITA props: audience, platform, product, props, and other props. Other authoring tools may have similar capabilities.

Answer 2

The way that I've done this in the past, at least in web-based documentation and Word documents, is to start with a less technical overview touching on the key points (high-level purpose, context, usages, etc.) and then work toward the most technical details at the end.

This way all of the documentation is in one place and people can basically work their way down the page/document until they find what they're looking for. It is still possible for information to get out of a sync, most often as a developer updates the technical parts of document to add a new feature or use-case but then forgets to explicitly add it to the earlier list of uses, but over time I just learned to work my way from top to bottom (or bottom to top if that seemed easier) and make all the necessary updates to each section.

You can also separate this into a few major sections so people can skip down to what they need. For example:

1. Summary Purpose
2. Features/Use-Cases
3. Technical Details

Or whatever sections make sense for the range of people that may need to look at the documentation.

Another advantage of this approach is that while all of the information is together in one document if you want to share only the higher level information with someone you can simply remove it from bottom up until you hit the level of documentation that is most appropriate for their needs.