Atomic Text Supercollider
November 2, 2015 3:25 PM Subscribe
Somehow I'm the guy who is ultimately responsible for writing and maintaining all of the manuals for our hardware and software products. This is a pain in the neck job that's not getting done, and I know how to describe the tool I think I need in order to relieve the pain. But does it exist?
Right now, the public-facing documentation for our products are scattered to the winds: google docs, PDFs in a dropbox, a desk.com-based knowledge base. The manuals have pictures and rich text, tables, footnotes, and, for electronic versions, links for within themselves and external resources as well. It's a snowstorm of content, and I'm looking for the right shovel.
Our products are in ways very similar. We've got the transmitter product (with several hardware and software variations) and the receiver product (likewise). When it comes down to it, the core transmitter tech is the same across all transmitter products, which vary mainly in features and UI. Likewise the receiver tech is kinda the same across all such products.
What I'm pretty sure I need is a kind of document management system, where I can create and store sections -- atoms -- of the manual separately. One atom might be the document describing tuning the right frequency, while another is about how to get support, while another atom is what inputs are supported. Those atoms are common to all manuals. Other atoms are not: the TX 10K supports wormholes, but the budget-minded TX 2K does not, so I need a wormhole page just for the TX 10K.
I want a thing that stores all the atoms in some useful fashion, and lets me create documents by, for the most part, telling it which atoms go in there. Updating the "how to contact support" page in all manuals should be as simple as changing the contact-support atom. If I can make "sub-manuals" which are pre-composed of "transmitter tech core features" atoms, which I could drop into the middle of the manuals for the 10000 and the 2000, that'd be super.
Does it exist? Can I get it for free? Can I run it without having to run a server to support it? (Any local server at all could be difficult to arrange; I don't just mean a dedicated server. However, if the product is right, the resource can be summoned.) Will a wiki do this well?
Bonus points if I can generate .chm (or whatever they're called these days) Windows help files from the lot. Thanks in advance.
Right now, the public-facing documentation for our products are scattered to the winds: google docs, PDFs in a dropbox, a desk.com-based knowledge base. The manuals have pictures and rich text, tables, footnotes, and, for electronic versions, links for within themselves and external resources as well. It's a snowstorm of content, and I'm looking for the right shovel.
Our products are in ways very similar. We've got the transmitter product (with several hardware and software variations) and the receiver product (likewise). When it comes down to it, the core transmitter tech is the same across all transmitter products, which vary mainly in features and UI. Likewise the receiver tech is kinda the same across all such products.
What I'm pretty sure I need is a kind of document management system, where I can create and store sections -- atoms -- of the manual separately. One atom might be the document describing tuning the right frequency, while another is about how to get support, while another atom is what inputs are supported. Those atoms are common to all manuals. Other atoms are not: the TX 10K supports wormholes, but the budget-minded TX 2K does not, so I need a wormhole page just for the TX 10K.
I want a thing that stores all the atoms in some useful fashion, and lets me create documents by, for the most part, telling it which atoms go in there. Updating the "how to contact support" page in all manuals should be as simple as changing the contact-support atom. If I can make "sub-manuals" which are pre-composed of "transmitter tech core features" atoms, which I could drop into the middle of the manuals for the 10000 and the 2000, that'd be super.
Does it exist? Can I get it for free? Can I run it without having to run a server to support it? (Any local server at all could be difficult to arrange; I don't just mean a dedicated server. However, if the product is right, the resource can be summoned.) Will a wiki do this well?
Bonus points if I can generate .chm (or whatever they're called these days) Windows help files from the lot. Thanks in advance.
Best answer: just extending vogon_poet's suggestion - you can do similar but use markdown (or a bunch of other formats) instead of latex, along with the excellent pandoc package. that gives you an (arguably) nicer format to write in, but more pain if you want to tweak formats etc. pandoc will also generate man files - it might even do windows help for all i know.
but this is very much a hack-it-together approach.
posted by andrewcooke at 4:00 PM on November 2, 2015
but this is very much a hack-it-together approach.
posted by andrewcooke at 4:00 PM on November 2, 2015
You can integrate readthedocs (rtd) with a Github repository. If you manage separate documents as submodules of a repository, you could manage your "atoms" that way. With Git tags, you get versioning for free, which can be very useful for pushing new and old versions of documents. The engine underneath rtd renders HTML, PDF and eBook formats from your ReStructuredText ("ReST") -formatted documentation files. The default themes can be replaced or modified, if you have need to customize the look of the output.
posted by a lungful of dragon at 4:01 PM on November 2, 2015
posted by a lungful of dragon at 4:01 PM on November 2, 2015
Adobe FrameMaker is the usual enterprisey tech-pubs answer.
DocBook is also good at this sort of thing; the HW team at work use it for their documentation workflow which has a lot of generation and inclusion, ultimately outputting to PDF.
posted by We had a deal, Kyle at 4:03 PM on November 2, 2015
DocBook is also good at this sort of thing; the HW team at work use it for their documentation workflow which has a lot of generation and inclusion, ultimately outputting to PDF.
posted by We had a deal, Kyle at 4:03 PM on November 2, 2015
Best answer: The industry-standard answer to this is DITA. Although DITA is just XML, and there are some low-level open-source tools for working with it, it seems that tools that normal humans might want to use are proprietary and very expensive.
I've been farting around with Pandoc, using its extended flavor of Markdown to convert files. Just today, I was converting a bunch of files to ICML and flowing them into an Indesign file. I use a Mac, and I've been relying on OS X's file-tagging, so I have a folder of source files, each of which are tagged with all of the target "binders" that they go into; then I view all the files tagged for the binder I want to work on, and run them through Pandoc, which concatenates them into a single target file. The system isn't perfect, and I've found that it's sometimes difficult to achieve an appropriate level of "atomicity." I'm sure if I knew shell scripting, I could make it work better for me.
posted by adamrice at 4:40 PM on November 2, 2015 [1 favorite]
I've been farting around with Pandoc, using its extended flavor of Markdown to convert files. Just today, I was converting a bunch of files to ICML and flowing them into an Indesign file. I use a Mac, and I've been relying on OS X's file-tagging, so I have a folder of source files, each of which are tagged with all of the target "binders" that they go into; then I view all the files tagged for the binder I want to work on, and run them through Pandoc, which concatenates them into a single target file. The system isn't perfect, and I've found that it's sometimes difficult to achieve an appropriate level of "atomicity." I'm sure if I knew shell scripting, I could make it work better for me.
posted by adamrice at 4:40 PM on November 2, 2015 [1 favorite]
Best answer: I've never bitten the bullet and learned LaTeX, but I have worked on several projects that used ASCII Doc successfully (the link is to a specific Ruby implementation). It's not perfect, but it does support importing common bits from external files. The real win for me is that at the end of the day it is a text file. This makes it possible to version and diff the documentation in a way I was never able to with Google docs/word/PDF/etc.
posted by phil at 5:25 PM on November 2, 2015
posted by phil at 5:25 PM on November 2, 2015
This thread is closed to new comments.
You would need one file per "atom". Then for each "submanual", you could use the \input command to load each atom you want. At the top level, you'd have a master file for each manual, with an \input for every atom or submanual you want.
To produce a manual, you would simply compile one of the top-level files. This would create nicely-formatted output based on the current versions of all the atoms and submanuals it includes. You could even write a short script or use GNU Make to automatically compile each manual.
The nice thing about LaTeX is that it's just plain text source code, so you can put it in a version control system like Git to keep track of your history and maybe different branches. And there are editors like LyX to make it a little friendlier to use.
Just Googling, it looks like there are workflows for going from LaTeX to HTML to .chm but I don't know enough to evaluate them.
LaTeX can do pictures, rich text, tables, footnotes, and links. One thing you don't get is super-fine-grained control over formatting.
posted by vogon_poet at 3:47 PM on November 2, 2015 [2 favorites]