5

Our software documentation set (for a SQL analytics database platform) is large, because SQL and databases have many pieces. Often a single statement, function, or feature will be highly related to a few others, and in the past people have (manually) added "related information" sections to pages to make it easier for people to find them. This means that if you're, for example, reading the documentation about creating tables, you have easy access to the documentation about altering them and dropping them.

But manual processes are messy and inconsistent. I've come across topics in our documentation that list all the relevant links that existed at the time, but later something got added and nobody found and updated that list. Meanwhile, a similar list on another page did get updated because someone noticed. Messy! This method of "managing" sets of related topics just doesn't scale for a documentation set with thousands of topics maintained by several writers over a period of years.

What I'd like to be able to do instead is to have information that is intrinsic to each topic, rather than extrinsic -- something like tags here on Stack Exchange. The idea would be that writers could (but would not have to) apply one or more tags to a topic, and the HTML build output would show those tags somehow, and clicking on a tag would take you to a page with links to all the topics that have that tag and, if possible, a short introduction (like our tag wikis).

We are using Madcap Flare to produce our documentation. The documentation source is Flare's XML (basically HTML with some extra elements), and the output is HTML. We can add Javascript into the output (we do this already for our search). We use Jenkins to manage our builds, so we can add pre- and post-build scripts around the invocation of the Flare build engine.

I think the things we need are:

  • a way to add tags in the XML source

  • a way, at build time, to generate the tag pages and link to them from all the tagged topics

Is this a solved problem already? Are there scripts or other tools that already exist that we can add to our Flare project and build?

  • I am a complete ignorant about Flare, but googling around I saw the existence of Index keywords. To me, they seem intrinsic to the specific doc. Are these the kind of things you were looking for? – NofP Mar 27 at 21:23
  • Alternatively you could use standardised bookmarks, and have the production code generate a map based on shared bookmarks. – NofP Mar 27 at 21:25
  • @NofP I'm looking for something that would be visible on the page, so when you're reading the reference page for "create thingy" you can click on a "thingy" tag to see the reference pages for "alter thingy" and "delete thingy" and the topic in the admin guide about managing thingies. Using an index to build tags sounds interesting, if we can work out the "visible on those pages" part. – Monica Cellio Mar 27 at 22:07
  • 2
    Just got this via Twitter. Looks like a useful lead. – Monica Cellio Mar 29 at 19:04
  • 1
    I haven't yet figured out how to turn concept markers (that Twitter lead) into what I want. :-( I know how to generate a "see also" list on every page with links to all the other pages, but that's noisy. Even if I could make that "see also" list be collapsible (and start collapsed), that'd probably be workable. But I can't figure out from their documentation how to do that and my minimal CSS and Javascript clues are insufficient. – Monica Cellio Apr 2 at 15:07
2

Note: I'm not an expert on Flare, but I've been using it for a few months. I've learned a lot, but I still have a lot to learn.

From what I understand, it sounds like you could use what Flare calls concepts. You can use concepts to have a "See Also" link/button. This would be similar to a "related information" section, but cleaner. When a writer adds a topic that is related to another one, they can just attach those two with a concept.

Alternatively, you can probably use cross-references. However, I think you can cross-reference only one topic each.

I hope this helps or at least steers you in the right direction!

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.