10

Scenario

I need to create and maintain a user documentation for a system of which there are different instances in use by different target groups. There are several levels of integration with other systems, several development stages, several regional production deployments. Not all of these instances have the same feature set (e.g. some features are just for tests, some features might be regionally limited et cetera).

Additionally the system consists of single services that may or may not be deployed together which affects the feature characteristic of the overall system as well.

Challenge

Finding a system that helps any user with one documentation with feasible effort. Currently the approach is to always document the latest development iteration in a versioned wiki system and indicate functionalities that are "just" testing functionalities. Is there a better way to document such fluid systems?

migrated from techcomm.stackexchange.com Feb 20 '18 at 15:22

  • What do you use for version control and what do you use configuration management? – Lefty G Balogh Jan 29 '18 at 20:56
  • You commented below that you're using Confluence. Are you using the Scroll Versions plugin? If not, how are you managing versions? – Robert Lauriston Feb 1 '18 at 17:26
  • @RobertLauriston currently we don't use that. We only have one state of documentation, the latest. (The pages have a history but that's not linked to the system version.) In the past in a related project we noticed that Scroll Versions tends to increase the confusion rather than decreasing it. – Helmar Feb 2 '18 at 15:03
10

What kind of software do you use for content development? I've found that branching is a good way to address version control if you have a need to support multiple versions simultaneously, but you would need a Content Management System (CMS) or authoring tool that has this type of functionality. You also need to consider how the information is delivered and whether that system has the functionality you need.

With branching, you can create, edit, and manage different versions of content in parallel. For example, you might edit the current version, let's call it 1.0, in a master branch. Once you've released your content for v 1.0 you would branch that content. This basically involves making an exact copy of the publication. Then, you can edit in the master branch to develop content for v 1.1, while still maintaining v 1.0 separately. You can also publish each version to provide accurate support to your end users for those versions.

Additionally, if you have a need to publish different content for different audiences, you might consider using conditional processing. For example, if you need to publish certain content on "testing" features for an internal audience only, you could tag those features "internal" or "testing" and filter the published content accordingly to include or not include that content. Similarly, you could conditionalize content for integrations, specific audiences, etc.

I work in a DITA CMS that has all these functionalities, so again, you would need to have a system or systems that can support these functions.

  • If you have good conditional processing and versioning in place, I suggest also investing in the user experience of your docs. Say, present readers with a screen where they can select their configuration and get a filtered list of resources applicable to their case. – Iva Koevska Jan 30 '18 at 15:15
  • Atlassian Confluence is our current documentation tool. – Helmar Jan 30 '18 at 16:52
1

I use madcap flare, and using condition tags allows you to produce 2 versions from the same content.

1

Paligo has an integrated DocBook CMS with branching, profiling, and various reuse features that make it relatively easy to create and maintain multiple versions of the same documentation. I branch a publication (collection of topics) after each release (1.1, 1.2, etc.). Then I branch individual topics in the new branch to reflect changes in that release. I can also edit an unbranched topic to make corrections in all the releases that share the topic.

You can use the same features to create docs for multiple variations of an individual release.

I migrated from Confluence using Scroll DocBook Exporter and with help from Paligo tech support (included in the subscription) it was pretty smooth as such things go. Any future customer doing the same would probably benefit from a lot of lessons Paligo learned from my experience.

I think it's cost-effective for documentation groups that are too small to justify the cost of building a system around a DITA CMS. You might want to look at Author-it Cloud and MadCap Central as well.

0

The method Splunk uses for their documentation is to use a per-version structure (though oftentimes the doc is the same for two different versions of the tool), and allow the reader to pick which version they want to read.

So you might be looking at 7.0.2, or 6.5.1, or 6.2.3, or any other possible version.

The URLs look like the following:

http://docs.splunk.com/Documentation/Splunk/7.0.2/Knowledge/Configurecalculatedfieldswithprops.conf
http://docs.splunk.com/Documentation/Splunk/6.5.1/Knowledge/Configurecalculatedfieldswithprops.conf
http://docs.splunk.com/Documentation/Splunk/6.2.3/Knowledge/Configurecalculatedfieldswithprops.conf

While I don't know what powers their system under the hood, I do know the doc team publishes docs for new versions when new versions release. And that old versions' docs are kept around more-or-less forever.

  • Splunk's system is based on MediaWiki. There's an open-source version called PonyDocs but it's based on a discontinued version of MediaWiki. – Robert Lauriston Feb 2 '18 at 19:12
  • I looked at PonyDocs a few years ago at a previous job and we couldn't get it to work. – Robert Lauriston Feb 2 '18 at 19:18
  • @RobertLauriston - not surprised it's MediaWiki, MW is a great tool – warren Feb 4 '18 at 3:47

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.