It's a thousand pages, give or take a few
November 12, 2014 7:30 AM Subscribe
TechWritingFilter: As a lone writer, what tools should I use to create amazing user- and developer-facing documentation?
I've just been hired as a lone writer at a startup. I'm their first tech writer, ever, and they've been using MediaWiki. It's not ideal.
I'm able to choose to do whatever the hell I want, with the caveat that everyone wants the docs to be gorgeous, well-organized, and easy to use. My model is here. Those docs are beautiful and easy to use. How do I do that? Do I need to go learn front-end development too?
I'm used to writing in DITA, but I'm not sure it makes sense for our documentation, because we don't need to deliver in multiple formats (just web). I'll really miss conditionalizing and conrefs, though. Can I just do that in HTML and forget DITA? (The internet seems to say I need JavaScript...)
I've considered several publishing solutions, including ePub/Webworks/Reverb, easyDITA, FluidTopics, Componize, and even sticking with a wiki like Confluence. None of these solutions appear to enable me to create simple, beautiful, well-organized, minimalist documentation. What gives? Am I missing something? What do you guys use? Do I have to try to convince my devs to build something from scratch? Help!
I've just been hired as a lone writer at a startup. I'm their first tech writer, ever, and they've been using MediaWiki. It's not ideal.
I'm able to choose to do whatever the hell I want, with the caveat that everyone wants the docs to be gorgeous, well-organized, and easy to use. My model is here. Those docs are beautiful and easy to use. How do I do that? Do I need to go learn front-end development too?
I'm used to writing in DITA, but I'm not sure it makes sense for our documentation, because we don't need to deliver in multiple formats (just web). I'll really miss conditionalizing and conrefs, though. Can I just do that in HTML and forget DITA? (The internet seems to say I need JavaScript...)
I've considered several publishing solutions, including ePub/Webworks/Reverb, easyDITA, FluidTopics, Componize, and even sticking with a wiki like Confluence. None of these solutions appear to enable me to create simple, beautiful, well-organized, minimalist documentation. What gives? Am I missing something? What do you guys use? Do I have to try to convince my devs to build something from scratch? Help!
Two solutions I've used as a lone tech writer are MadCap Flare and Jekyll.
Flare is pretty nice. It's designed for topic-based authoring, but it doesn't force you to do DITA. It's not really a full CCMS -- you'd probably want to hook it up to a version control tool like Subversion -- but for a lone writer, that's probably not a huge problem. In my experience, Flare is quite popular with freelance tech writers. There are a few out-of-the-box templates you can use, but of course you can customize the presentation as much as you want. Oh, and you can conditionalize text, insert snippets into topics, etc. It's really nice for that.
Jekyll is a static site generator that some people use for blogging, but it seems to be fairly popular among open-source projects. You'd have to build the site, but there's a blogging framework called Octopress that has a lot of navigation and styling functionality built in. These two aren't "technical writing tools", of course; they're just tools that you can use to publish stuff to the web. Organizing the docs well is up to you. ;)
Have you looked at Read the Docs? See the Ansible documentation to see it in action.
(Just to cover some other tools: I've used Author-it, FrameMaker/Robohelp, and Vasont, but I don't think any of those are what you're looking for.)
Do I need to go learn front-end development too?
To make a site like the Parse site, you'd need to at least get familiar with front-end development. Or find a really good out-of-the-box template. Unfortunately Guess doesn't show much about what they might be using.
posted by neushoorn at 8:08 AM on November 12, 2014 [1 favorite]
Flare is pretty nice. It's designed for topic-based authoring, but it doesn't force you to do DITA. It's not really a full CCMS -- you'd probably want to hook it up to a version control tool like Subversion -- but for a lone writer, that's probably not a huge problem. In my experience, Flare is quite popular with freelance tech writers. There are a few out-of-the-box templates you can use, but of course you can customize the presentation as much as you want. Oh, and you can conditionalize text, insert snippets into topics, etc. It's really nice for that.
Jekyll is a static site generator that some people use for blogging, but it seems to be fairly popular among open-source projects. You'd have to build the site, but there's a blogging framework called Octopress that has a lot of navigation and styling functionality built in. These two aren't "technical writing tools", of course; they're just tools that you can use to publish stuff to the web. Organizing the docs well is up to you. ;)
Have you looked at Read the Docs? See the Ansible documentation to see it in action.
(Just to cover some other tools: I've used Author-it, FrameMaker/Robohelp, and Vasont, but I don't think any of those are what you're looking for.)
Do I need to go learn front-end development too?
To make a site like the Parse site, you'd need to at least get familiar with front-end development. Or find a really good out-of-the-box template. Unfortunately Guess doesn't show much about what they might be using.
posted by neushoorn at 8:08 AM on November 12, 2014 [1 favorite]
I do very little tech writing any more, so this might not help. You may want to check out Information Mapping which was developed by Robert Horn, and any tools they might have or recommend.
posted by Altomentis at 12:21 PM on November 12, 2014
posted by Altomentis at 12:21 PM on November 12, 2014
MediaWiki content can be exported to a variety of formats.
I am a few years out of touch on this topic, but have you looked into LaTeX?
posted by 1367 at 4:36 PM on November 12, 2014
I am a few years out of touch on this topic, but have you looked into LaTeX?
posted by 1367 at 4:36 PM on November 12, 2014
(Sorry - I somehow missed that you were looking towards online documentation, which is not what LaTeX is designed to do. I was thinking of documentation that would ultimately be in print or PDF format.)
posted by 1367 at 4:42 PM on November 12, 2014
posted by 1367 at 4:42 PM on November 12, 2014
FWIW the tech writers at the place I work use MadCap Flare .... I hear it has its own set of quirks and issues just like anything else.
posted by Mr. Papagiorgio at 8:10 PM on November 12, 2014
posted by Mr. Papagiorgio at 8:10 PM on November 12, 2014
I've been thinking about this a lot lately. I think there are three questions to answer:
1. How do you write it?
2. How do you make it look good?
3. How do you host it?
For 1: Asciidocs makes a lot of sense for this kind of thing, but there aren't a lot of tools that support it, so you don't have a lot of flexibility. Markdown is not quite as good a fit for documentation, but tools are ubiquitous and rich. If you haven't already checked out Pandoc, do so. It supports both Asciidoc and Markdown (with numerous extensions).
Points 2 and 3 kind of overlap. For a static site, you could pipe your markdown/asciidoc documents through Pandoc with a custom template, and then sync that to the web. Although Wordpress was not really built for it, I'm leaning towards using it with a theme built on Bootstrap. Bootstrap gives you a lot of "utility" styles for free that are helpful with documentation; some of the Bootstrap-based themes for WP give you shortcodes for taking advantage of these (which detracts from portability, so not without drawbacks). There are also numerous skins for bootstrap, and one of those could be used as a foundation for a WP theme, or for some other kind of CMS or site generator.
posted by adamrice at 3:23 PM on January 26, 2015
1. How do you write it?
2. How do you make it look good?
3. How do you host it?
For 1: Asciidocs makes a lot of sense for this kind of thing, but there aren't a lot of tools that support it, so you don't have a lot of flexibility. Markdown is not quite as good a fit for documentation, but tools are ubiquitous and rich. If you haven't already checked out Pandoc, do so. It supports both Asciidoc and Markdown (with numerous extensions).
Points 2 and 3 kind of overlap. For a static site, you could pipe your markdown/asciidoc documents through Pandoc with a custom template, and then sync that to the web. Although Wordpress was not really built for it, I'm leaning towards using it with a theme built on Bootstrap. Bootstrap gives you a lot of "utility" styles for free that are helpful with documentation; some of the Bootstrap-based themes for WP give you shortcodes for taking advantage of these (which detracts from portability, so not without drawbacks). There are also numerous skins for bootstrap, and one of those could be used as a foundation for a WP theme, or for some other kind of CMS or site generator.
posted by adamrice at 3:23 PM on January 26, 2015
This thread is closed to new comments.
posted by davidpriest.ca at 7:57 AM on November 12, 2014