Looking for best practices for creating a "living" manual
June 19, 2014 2:13 PM Subscribe
My co-workers and I have created a "living" (continually updated) manual for some processes we do with some associated agencies, but none of us are technical writers or copy editors, so we're looking for assistance in the structure and appearance. Please share your experiences, guides, and tutorials for creating and managing a manual that won't remain in a fixed form.
We hired consultants to help us put together the first draft, but it was a mess, and the contract expired. Since then, we've expanded and updated the manual, but it's still pretty rough, so we're looking to higher a local professional to polish what we have. What questions should we ask, or what requirements should we have in place, beyond the final format needs to be something we can continue to modify in-house? We're mostly working with Microsoft Office 2010, but we've talked about using Publisher or some other software to build and manage the document. At my last place of work, we had one person who had made the most of MS Word and created a number of hyperlinked Word documents, but we're not even there yet with what we have now.
Conversely, or additionally, what are best practices for managing such a document in-house? We're dealing with tracking changes across sections, updating some dates and deadlines that are repeated in a few different places, so some system to track repeated references or deadlines would be key, if nothing else.
Alternatively to all this, I've been thinking of managing this as a website, as cross-linking is a basic feature, and it's fairly straight-forward to make a widely compatible website, versus version management with MS Word. Thanks!
We hired consultants to help us put together the first draft, but it was a mess, and the contract expired. Since then, we've expanded and updated the manual, but it's still pretty rough, so we're looking to higher a local professional to polish what we have. What questions should we ask, or what requirements should we have in place, beyond the final format needs to be something we can continue to modify in-house? We're mostly working with Microsoft Office 2010, but we've talked about using Publisher or some other software to build and manage the document. At my last place of work, we had one person who had made the most of MS Word and created a number of hyperlinked Word documents, but we're not even there yet with what we have now.
Conversely, or additionally, what are best practices for managing such a document in-house? We're dealing with tracking changes across sections, updating some dates and deadlines that are repeated in a few different places, so some system to track repeated references or deadlines would be key, if nothing else.
Alternatively to all this, I've been thinking of managing this as a website, as cross-linking is a basic feature, and it's fairly straight-forward to make a widely compatible website, versus version management with MS Word. Thanks!
Sounds like a good use case for creating a department "wiki" site, which could be hosted locally on a server of even from a dedicated desktop machine. DokuWiki is one popular, open/freeware package for this. There are others, but it's a good place to start.
Also, on a practical level, the primary authors of this document should come up with a style guide. That way, multiple people can work on the document, but the capitalization and formatting of headings, sections, and key terms can be held to a common standard for consistency.
posted by mosk at 2:33 PM on June 19, 2014
Also, on a practical level, the primary authors of this document should come up with a style guide. That way, multiple people can work on the document, but the capitalization and formatting of headings, sections, and key terms can be held to a common standard for consistency.
posted by mosk at 2:33 PM on June 19, 2014
Yeah, a wiki is much less reliant on a set structure, and much more amenable to the structure being changed than a linear Word document.
The best feature of a wiki is that you can very easily link documents and terms between pages. To create links in most wikis, you type the wiki page name surrounded by brackets. That's it. This makes it very easy to create things like tables of contents, or cross-references to different areas of the document.
Wikis do require learning a basic syntax when editing text - things like surrounding text with brackets for links and stars for bold.
The one thing I don't have is a great recommendation for a wiki to go with. I've used a bunch of them, but I haven't found one that hits all of being easy to setup, easy to insert photos, and being affordable. If you're a business without a lot of IT staff, I'd definitely look at something hosted in the cloud.
posted by cnc at 5:38 PM on June 19, 2014
The best feature of a wiki is that you can very easily link documents and terms between pages. To create links in most wikis, you type the wiki page name surrounded by brackets. That's it. This makes it very easy to create things like tables of contents, or cross-references to different areas of the document.
Wikis do require learning a basic syntax when editing text - things like surrounding text with brackets for links and stars for bold.
The one thing I don't have is a great recommendation for a wiki to go with. I've used a bunch of them, but I haven't found one that hits all of being easy to setup, easy to insert photos, and being affordable. If you're a business without a lot of IT staff, I'd definitely look at something hosted in the cloud.
posted by cnc at 5:38 PM on June 19, 2014
You're on the right track with a website. There are tons of wikis out there that are designed for just such a project. I use Confluence all the time to collaborate with my clients (my job involves a lot of documenting custom development projects and various business processes), but there's a ton of feature overlap, so you could throw a dart and still probably find something that meets your needs without doing an exhaustive search.
posted by nobejen at 6:28 PM on June 19, 2014
posted by nobejen at 6:28 PM on June 19, 2014
cnc is right about it being difficult to find something out-of-the-box that meets a long list of specific requirements, but if you're already doing this in Word, I think you'll be okay. If you want to explore using a wiki for other purposes, you'll want to be a bit more selective.
Confluence (my personal favorite) has a hosted version that's very inexpensive (starts at $10/mo).
Save yourself the trouble, and stick with something hosted. I wouldn't hesitate to tackle your project with the hosted version.
You can easily copy and paste images and attachments in Confluence (without any laborious browse->select->upload nonsense), and there are a ton of keyboard shortcuts. These things matter to me because I'm personally offended by unnecessary mouse clicks. They might not matter to you.
I'm not affiliated with Confluence in any way (other than being a customer). I'm just a big fan.
posted by nobejen at 6:38 PM on June 19, 2014
Confluence (my personal favorite) has a hosted version that's very inexpensive (starts at $10/mo).
Save yourself the trouble, and stick with something hosted. I wouldn't hesitate to tackle your project with the hosted version.
You can easily copy and paste images and attachments in Confluence (without any laborious browse->select->upload nonsense), and there are a ton of keyboard shortcuts. These things matter to me because I'm personally offended by unnecessary mouse clicks. They might not matter to you.
I'm not affiliated with Confluence in any way (other than being a customer). I'm just a big fan.
posted by nobejen at 6:38 PM on June 19, 2014
Response by poster: Thanks for all the good ideas about running on a wiki, but there are some significant complications that push me towards Office-type document management:
1. my department has very strict web controls, to the point that we have to justify adding individual web pages to the broader Professional Site, so that's pushing us towards "unofficial" hosting options (aka no on company web space, and possibly something we'd get grief about paying for).
2. there is a strong desire within my group to produce something hard-copy, even though we'll be continuing to update the document over the coming quarters/years.
With that, my idea of a website or a wiki might not really fit with the current company structure. In retrospect, that was a derail I provided to my question.
posted by filthy light thief at 8:21 PM on June 19, 2014
1. my department has very strict web controls, to the point that we have to justify adding individual web pages to the broader Professional Site, so that's pushing us towards "unofficial" hosting options (aka no on company web space, and possibly something we'd get grief about paying for).
2. there is a strong desire within my group to produce something hard-copy, even though we'll be continuing to update the document over the coming quarters/years.
With that, my idea of a website or a wiki might not really fit with the current company structure. In retrospect, that was a derail I provided to my question.
posted by filthy light thief at 8:21 PM on June 19, 2014
Please share your experiences, guides, and tutorials for creating and managing a manual that won't remain in a fixed form.
You should look into topic-based authoring, which is the dominant model in the technical writing world these days. It's a modular approach to content creation, and it can help you avoid a lot of pain related to things like document structure and flow. It also makes the maintain/review/update cycle easier, because you can handle each topic individually.
We're mostly working with Microsoft Office 2010, but we've talked about using Publisher or some other software to build and manage the document.
This immediately made me think of MadCap Flare. You can use Flare to organize your content and publish it, even in hard-copy formats like PDF. And you can keep Word as your authoring tool if you want, though Flare's built-in editor is pretty user friendly. Flare can even help with this: updating some dates and deadlines that are repeated in a few different places via features like variables and snippets.
Flare doesn't do the version management part, but you can easily hook it up to a Sharepoint server or to another revision control system. There might also be ways that you can do some kind of manual version control of your Word source documents.
posted by neushoorn at 1:13 AM on June 20, 2014
You should look into topic-based authoring, which is the dominant model in the technical writing world these days. It's a modular approach to content creation, and it can help you avoid a lot of pain related to things like document structure and flow. It also makes the maintain/review/update cycle easier, because you can handle each topic individually.
We're mostly working with Microsoft Office 2010, but we've talked about using Publisher or some other software to build and manage the document.
This immediately made me think of MadCap Flare. You can use Flare to organize your content and publish it, even in hard-copy formats like PDF. And you can keep Word as your authoring tool if you want, though Flare's built-in editor is pretty user friendly. Flare can even help with this: updating some dates and deadlines that are repeated in a few different places via features like variables and snippets.
Flare doesn't do the version management part, but you can easily hook it up to a Sharepoint server or to another revision control system. There might also be ways that you can do some kind of manual version control of your Word source documents.
posted by neushoorn at 1:13 AM on June 20, 2014
In my experience, unless a tool is very easy to use and similar to existing workflows, collaborative and ongoing documentation projects tend to peter out. Google Docs works pretty well for the purpose for those reasons. (and perhaps the online version of MS Office has similar capabilities now?)
posted by Candleman at 2:10 AM on June 20, 2014
posted by Candleman at 2:10 AM on June 20, 2014
This thread is closed to new comments.
posted by karbonokapi at 2:30 PM on June 19, 2014 [1 favorite]