Post History
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...
#4: Post edited
by
Monica Cellio
·
2020-11-17T04:02:07Z (about 4 years ago)
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 topicsIs this a solved problem already? Are there scripts or other tools that already exist that we can add to our Flare project and build?
- 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 Codidact. 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. We already use some pre-build steps to inject content into the source after checking it out from source control and before invoking madbuild.
- 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?
#3: Attribution notice added
by
System
·
2019-12-08T11:30:46Z (almost 5 years ago)
Source: https://writers.stackexchange.com/q/44027 License name: CC BY-SA 3.0 License URL: https://creativecommons.org/licenses/by-sa/3.0/
#2: Initial revision
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?
#1: Imported from external source
by
System
·
2019-03-25T20:58:51Z (over 5 years ago)
Original score: 5