Author Topic: Instruction manual creation recommendations? (Read 31900 times)

superboyac · « **on:** May 10, 2010, 04:25 PM »

DC, please offer any advice you have on this subject:

I need to create an instruction manual document at work. Everything I have is in MS Word right now. There are several files (for each section), but it's really one document that will combine all the sections. I am the one who is handling all the files. Meaning, it's not some collaborated effort or anything, so I don't need some kind of software that will allow real-time simultaneous editing with a bunch of people. However, I would like to keep track of the changes that are made (I don't plan on using anything other than MS Word's tracking tools).

People (supervisors, other people) will want to see the files every once in a while, so I don't want to do it in anything other than Word, since that would complicate things with the mostly non-poweruser crowd here.

So, my question is, what is the best way to handle this situation? All I can think of is to carefully organize all the files, keep track of the changes in MS Word. The only additional thing i would do is use some kind of task management software (InfoQube, most likely) to keep track of the status of all the tasks. For example, if I am waiting for someone to submit something, or if I have a question about something that can't be answered right now...all these things need to be managed carefully, so nothing gets missed.

The other thing is an easy way to keep the styles consistent. Titles, headers, footers, indentations, page numbering, table of contents, etc. This reminds of the other thread about "Powerpoint sucks" thread by JavaJones. It would be nice to have everything as integrated as possible. For example, if I add a page somewhere, the TOC gets automatically updated, along with all the other affected page numbers. Stuff like that. The hard part is that I would like to keep this all in Word.

i was initially thinking that it would be nice to use a program like Help + Manual for something like this. Then I can treat the content like webpages, and use css or something to control the styling. But i have to keep it in Word, so that's out.

The other thing I was thinking about is mouser's Form Letter Machine. I've spoken to him privately about it in the past, how it can be used as something just like I'm describing here. But I don't think anything like that exists right now.

So if anyone has any ideas, please let me know. As javajones said, be as creative and outside the box as you can!

JavaJones · « **Reply #1 on:** May 10, 2010, 04:33 PM »

Hehe, well I think someone's suggestion in my thread might work well for you: setup your styles and use a master document. Since it's just you doing everything, you'll have no problem adhering to the style guidelines. ToC handling is pretty automatic, sometimes you just need to manually force an update, but as long as you're using headers and other formatting correctly, it should all get in there. So really I think the best thing to do is make sure you're formatting the documents correctly and consistently from the beginning, and everything should flow from there.

I realize though that this is general advice rather than a specific technique or workflow. Hopefully it's helpful regardless.

- Oshyan

superboyac · « **Reply #2 on:** May 10, 2010, 04:36 PM »

Thanks Oshyan. I've never really played with Word's styling tools. At least not enough to know exactly what it's capable of. i have a feeling it's a lot more powerful than what most people think.

Do you think it would be better to have several files, or one large file? I'm going to go with one large file, and section it up inside the file using word's meta features for bookmarking or specifying start/finish of individual sections. I'm talking out of my ass...I don't know if Word can actually do that, but I would be shocked if it couldn't.

superboyac · « **Reply #3 on:** May 10, 2010, 04:38 PM »

The other thing is can I have a bunch of sections inside one document, each with their own page numbering scheme, and an overall TOC that can follow all of it?

JavaJones · « **Reply #4 on:** May 10, 2010, 04:59 PM »

Whether you want to use multiple files or a single depends IMO on your eventual output and use requirements. Are you printing this? Do you basically want a single "document" (e.g. book), but would think of doing it as separate files if it made it easier? In other words would you prefer to use 1 file, unless it's necessary/better/easier to use multiple? In that case I think you can probably use 1 file, although I'm uncertain about multiple ToCs in one DOC. Doing it as multiple files with a master document would be the logical choice then. Using a single file would simplify things as far as styling and whatnot goes though, so that's something to consider.

Setting up styles can be a bit of a pain in my experience. Might be better in 2k7 or 2k10 than 2k3, so if you're using a newer version you have possible cause for hope. But the most important thing is just to do it from the beginning if at all possible. This involves some pre-planning. Figure out for example how many levels of headings you'll need, from the top all the way down (without writing all the content first of course

), and then set all the heading formats up the way you want them. The alternative is to write all your content unformatted then format after. This could be ideal, if you can deal with the initial lack of formatting during writing, because it allows you to apply formatting only once you're fully aware of all the formatting needs of the document, but it's a luxury I've seldom seen it actually being possible to take advantage of...

- Oshyan

superboyac · « **Reply #5 on:** May 10, 2010, 05:11 PM »

Ugh...a couple of years ago, I made a thread here about how to use Word's styling features. It's such a pain in the flippin ass. Nothing is intuitive, nothing works the way you imagine, nothing is easy.

Can I do this:
I'll make a unordered list outline. I'll format it manually just the way I want with all my own spacing, indentations, bullet styles, font sizes...get everything exactly the way I want.

After I do that, is it possible to save that clump of text as a "style" and later, highlight a bunch of text, click on my new style I just saved, and, boom, have it work flawlessly? This better be possible, or else I'll be compelled to drop some F bombs about MS Word.

JavaJones · « **Reply #6 on:** May 10, 2010, 05:16 PM »

Yeah, um... you *should* be able to define a single style for one segment of text, but I don't think you can define a whole type of formatting and then apply that easily to a block of text, having it intelligently format based on positioning or something (not that I'm suggesting that's what you asked for). I also don't think you can just create e.g. a multi-level list, format it the way you want, and then create a multi-level list style out of that, where you could then apply e.g. level 3 to another bulletted list easily. That being said, as indicated in that other thread of yours, this may be easier in 2007 or 2010. Which version are you using now?

- Oshyan

superboyac · « **Reply #7 on:** May 10, 2010, 05:26 PM »

I'm on 2007 I've just tried it, and you are right...it doesn't let you save a whole block. Which is freaking stupid. I mean, how long has this program been around??! Once a year or so, these styling issues piss the hell out of me about Word. They come out with version after version after version, and have they once made the styling easier? No. The biggest thing they've done is add the styling buttons to the big ribbon now, but that's just one little improvement on the frontend. In the backend, they still use the same pain in the ass procedure to create list styles. None of options make any sense and they never work intuitively. Such a freaking pain.

And, of course, all the default, out of the box styles, are useless. Huge double and triple spaces everywhere, indentations equally obnoxious (like 1 inch between the bullet and first character). it's so stupid, I hate it so much. Then there's that scary/funny article 40hz posted in the powerpoint thread, which shows how obnoxious thos default list styles look in a presentation.

I still can't believe nobody has made some plugin or template, or SOMETHING, that makes this whole process much easier. Cmon, people, send me some list styles or something.

Geez...I am so pissed about this. MS Word is one of the most widely used programs available...microsoft has made a fortune on it, they have a billion programmers working on it, all the money in the world...and do they EVER make any useful improvements like this? No way! They add ribbons, they add buttons, they add a bunch of tiny little fancy features that most users will never think of using. yet, do they ever pay attention to the MAJOR things that people are clicking on 99% of the time? No. ARRRRGHGHGH.

JavaJones · « **Reply #8 on:** May 10, 2010, 06:12 PM »

I'm right there with you. This is actually one of my biggest frustrations with OpenOffice (and any other Office clone for that matter): they aren't just copying the good from MS Office, they're also copying the "bad" (IMHO, of course, hehe). Maybe it's just me and naive hope, but I can't help thinking that if OpenOffice came out with better formatting tools than Office, the kind of thing you mention e.g. select a series of formatted bullets with multiple levels and auto-create a style out of it that you can freely apply to any level of bullet, that it would really gain some respect against word and set itself apart. As it is OOo is left just being an also-ran, always compared to Word, which still has some advantages in terms of UI smoothness and certainly speed. But just imagine if OOo formatting systems were a step beyond Office 2k7 or 2k10 - wouldn't that spark some more legitimate comparison and debate? Wouldn't that be a lot more interesting? Doesn't that serve OOo's goals more?

I'm tired of everyone just trying to do the crappy things MS has done, only for free, or "open source", and somehow that's supposed to be enough. What about different, *better* ways of doing it? When it comes down to it, as you said, the ribbon is really just a different way to interface with the same old semi-broken styling system. There are a few improvements to be fair, but overall it's just a new way to interact with the same old tools. What about new tools, or at least *smarter* tools?

Adobe has just come out with CS5 Suites, and though they really have no major competition, they've added a pretty nice array of new features, including Content Aware Fill (which arguably had competition from a GIMP plugin well before its release, but let's ignore that for a moment

). Where is the Content Aware Fill equivalent in MS Word? Come on people!

- Oshyan

parkint · « **Reply #9 on:** May 10, 2010, 08:13 PM »

I would offer a word of warning: be sure to keep some sort of backup copy of EVERYTHING.
Especially with MSWord, there will be a time* when a user makes changes to a document and it becomes unreadable.
I am a big fan of git for version control & backup. I acknowledge that 'average users' are not able to understand the concepts of version control.
But, one of the great attributes of git is that all the revision information can be 'transported' easily (it is maintained in a single folder). I have done precisely this, in this way:

I have a 'controlled' copy of everything on a server (in a share only I have permission to)
Using git I can capture changes - as the 'updates' are passed to me by other users (in my case it is only ONE other person)
That server-backed copy of my files becomes the MASTER.

Good luck. Your task is complicated by the fact that, besides managing information (and the technical logistics) you must manage people and "The Idiot Principle" [a kin to The Peter Principle].

*When that occurs and you think back to this post, you can call me "Jeanne Dixon". LOL

PPLandry · « **Reply #10 on:** May 10, 2010, 08:17 PM »

Going back to the original tread subject...

So, my question is, what is the best way to handle this situation? All I can think of is to carefully organize all the files, keep track of the changes in MS Word. The only additional thing i would do is use some kind of task management software (InfoQube, most likely) to keep track of the status of all the tasks. (...)
-superboyac (May 10, 2010, 04:25 PM)

It seems to me a help authoring tool is what you want. Google "html help authoring word" gets you a whole bunch, one of them certainly supports multiple files (but ask yourself if you really need multiple files, why not a single file...)

I've used a Word add-on in a previous life, (don't remember which one, but could find it if you want) and was quite satisfied with the way it worked (a Word Add-in) and of the final result.

PPLandry · « **Reply #11 on:** May 10, 2010, 08:19 PM »

I would offer a word of warning: be sure to keep some sort of backup copy of EVERYTHING.
Especially with MSWord, there will be a time* when a user makes changes to a document and it becomes unreadable.
I am a big fan of git for version control & backup.
-parkint (May 10, 2010, 08:13 PM)

Or put the file in a Dropbox folder and every change will be saved and you can go back to a working copy if corruption occurs

JavaJones · « **Reply #12 on:** May 10, 2010, 08:58 PM »

Yeah, I was going to suggest DropBox (or similar) for "version control" and backup.

- Oshyan

40hz · « **Reply #13 on:** May 10, 2010, 10:13 PM »

For version tracking you might want to take a look at AutoVer, which has been getting some recent buzz on the freeware/software blogs.

AutoVer 1.4.1

AutoVer is a configurable automatic or real time backup and personal versioning system. It can be used as a simple real time backup or as a more complex, but transparent version control system (like a realtime incremental backup). The beauty of this system is that once you set it up (which is extremely simple) it does everything. No remembering to backup or to check in or check out files. Every time you save a file it is copied to your backup folder, drive or FTP server. You can include and exclude certain files and browse the backups with the Backup Explorer.

Great for backing up (or one way synchronising) your work or home documents to flash memory or saving every change you make to your source code or image files.

Link: http://beanland.net.au/AutoVer/

Ghacks and Download Squad, both did write-ups on it recently:

http://www.ghacks.ne...up-software-autover/

http://www.downloads...rs-got-your-back-up/

I haven't personally gotten a chance to try AutoVer yet. But you can be sure I will.

------

For really structured and complex documents, there's nothing that can compare to LyX. There's a learning curve that goes with it. But it's not a huge one. It's mostly learning that there's a more efficient way to handle the creation of documents than the wordprocessing paradigm.

Probably not a good match for this project. But it wouldn't hurt to tuck it in the back of your mind for future investigation if you anticipate doing a lot of tech writing. LyX/LaTeX can do just about anything (including change tracking and multiversioning) when it comes to document creation and editing.

Instruction manual creation recommendations?

Instruction manual creation recommendations?

Link: http://www.lyx.org/

JavaJones · « **Reply #14 on:** May 10, 2010, 10:42 PM »

Ah, LaTeX... I always see this being touted as the holy grail of "proper" document creation, and I see the theoretical advantages. But ironically I have yet to see a really nice looking LaTex document example. Is that just because the people creating them don't care to make them look fancy? Most of the examples I've seen are also math-oriented, and I know it has superior equation editing/syntax/whatever. But I still wonder how applicable it is to most of my projects...

- Oshyan

40hz · « **Reply #15 on:** May 10, 2010, 10:55 PM »

Mostly it's a tool for technical documents although it's proponents wax poetic about it being ideal for just about everything. Like most good tools, it all depends on what you want to do.

As far as nice looking docs go, that's up for subjective debate. I've seen some truly beautiful documents come out of LaTeX. But graphic and print design is its own discipline so don't expect everybody that uses something like LyX to be a designer.

You'll see the same thing with people who use Scribus, Quark Xpress or Adobe InDesign. Such tools may make your work easier and present you with expanded possibilities. But they still can't work miracles - or add something that isn't already there.

JavaJones · « **Reply #16 on:** May 10, 2010, 11:06 PM »

All fair points. I just wonder, is it really ideal for something like documentation? I don't know, I'm honestly asking.

- Oshyan

superboyac · « **Reply #17 on:** May 11, 2010, 12:39 AM »

Ah! latex...i remember using that for my grad courses in stat/math. it does offer more control over styling, that's for sure. I would consider using it personally, but not at work. It would bring up too many questions I have no desire to answer.

superboyac · « **Reply #18 on:** May 11, 2010, 12:42 AM »

Thanks Pierre, i'll look into the Word add-ons. 40hz, I'll take a look at the versioning tools also.

40hz · « **Reply #19 on:** May 11, 2010, 07:35 AM »

Ah! latex...i remember using that for my grad courses in stat/math. it does offer more control over styling, that's for sure. I would consider using it personally, but not at work. It would bring up too many questions I have no desire to answer.
-superboyac (May 11, 2010, 12:39 AM)

I hear you. I don't think there's a senior manager alive that didn't get the hots when hearing about the concept of WYGIWYM and think it was the answer to everything.

Yeah. Better forget LaTeX. You've got enough work to do already.

40hz · « **Reply #20 on:** May 11, 2010, 09:17 AM »

All fair points. I just wonder, is it really ideal for something like documentation? I don't know, I'm honestly asking.

- Oshyan
-JavaJones (May 10, 2010, 11:06 PM)

It's hard to say if it's ideal. It is a very good choice for a doc project. And it does get used for that. I have two clients that are heavily vested in LaTeX based authoring systems.

I think it all depends on how you think about and approach documentation.

IMHO a wiki is probably the most efficient way to create and maintain tech docs.

And you'll never know how much it pains me to say that.

Now If someone could just come up with a good way to convert a wiki into a decently formatted printed manual (with good typography) I'd feel far less of that pain.

superboyac · « **Reply #21 on:** May 11, 2010, 09:19 AM »

Now If someone could just come up with a good way to convert a wiki into a decently formatted printed manual (with good typography) I'd feel far less of that pain.
-40hz (May 11, 2010, 09:17 AM)

I second that! That would be a great tool, to take a wiki and print a nice manual with it. That's awesome.

PPLandry · « **Reply #22 on:** May 11, 2010, 10:00 AM »

Have you considered using Wikispace or better yet WetPaint for the content and then when completed, print to PDF or better still, export and compile to chm ?

superboyac · « **Reply #23 on:** May 11, 2010, 10:41 AM »

Have you considered using Wikispace or better yet WetPaint for the content and then when completed, print to PDF or better still, export and compile to chm ?
-PPLandry (May 11, 2010, 10:00 AM)

I have not, but they look interesting. The problem is I don't have much of a say in this. Just by using "fancy" Word features like Styles is sort of pushing it. I have to use Word documents. Whatever I do, everyone has to think I did it all in Word without much extra stuff.

The other thing is that 90% of this has already been completed, in Word. So it's not like I'm doing this from scratch. I'm basically putting the finishing touches on it. I probably should have mentioned that before.

Armando · « **Reply #24 on:** May 11, 2010, 11:18 AM »

Hi superboyac,

From what you're describing, it's a bit hard to know what would be the best solution. I think Pierre's suggestion would be the easiest to implement, that is if you don't worry about the formatting at first -- what I've noticed in these wiki collaboration software is that the documents quickly become a format mess. For the content though, it's pretty good.

I got your note on MS Word styles. Even if I don't use MS Word that much any more, I must say that using it without using styles means missing a lot of important features. Using styles is pretty straight forward, but once you've set a style, it's good to create a template and save it somewhere (as a *.dot file).

To use styles an Word outlines to their fullest, I found it works best to assign styles to levels and numberings. And then assign specific shortcut keys to these. I worked like that for many years and it's quick and easy.

Quickly :

1- In the "modify style" or "New Style" dialog, select your options -- but be careful with the "Style based on" option as this one means that modifying one style will modify the other.....

I tend to name my styles with level numbers : xyz1 xyz2 xyz3 xyz4 xyz5, or just use the MS provided level1, 2, 3, 4...

2- Then After everything has been set to your liking, link that style to an Outline Numbered scheme : Format--> Numbering-->Outline Numbered. Click on "Customize". You have many options there. The "level" Parameter is important as it will assign a level to your style, which will be usefull when you use the document map to navigate into a long document.

3- Then assign shortcuts to these styles : right click on a toolbar --> customize, then in the dialog, select the "Options" tab, go to categories and select styles. Assign specific keyb. short .there. (I use ctrl-0 to 9)

Not sure if that can be helpful. I know it's really nothing special and maybe laughable, but who knows.

[ EDIt : and then, use the "view" (menu) --> "Document map" feature to navigate into your document (assigning a shortcut to that is a good idea too). You can also work in Outline mode, which allows to move whole sections (levels) around, etc. Word has a pretty good outline I find. It's not IQ or anything, but it works well if one is working with a lot of text. ]