topbanner_forum
  *

avatar image

Welcome, Guest. Please login or register.
Did you miss your activation email?

Login with username, password and session length
  • Tuesday March 19, 2024, 1:38 am
  • Proudly celebrating 15+ years online.
  • Donate now to become a lifetime supporting member of the site and get a non-expiring license key for all of our programs.
  • donate

Last post Author Topic: Instruction manual creation recommendations?  (Read 28250 times)

PPLandry

  • Supporting Member
  • Joined in 2007
  • **
  • Posts: 702
    • View Profile
    • InfoQube Information manager
    • Read more about this member.
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #25 on: May 11, 2010, 11:22 AM »
what I've noticed in these wiki collaboration software is that the documents quickly become a format mess.
Correct me if I'm wrong, but I think superboyac doesn't need the collaborative aspects of these online wikis and all allow you to disable it, leaving only the public (or by invitation) viewing of the content
Real generosity toward the future lies in giving all to the present -- Albert Camus -- www.InfoQube.biz

Armando

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 2,727
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #26 on: May 11, 2010, 11:47 AM »
what I've noticed in these wiki collaboration software is that the documents quickly become a format mess.
Correct me if I'm wrong, but I think superboyac doesn't need the collaborative aspects of these online wikis and all allow you to disable it, leaving only the public (or by invitation) viewing of the content


Yes I noticed he said that. But I didn't get that your idea was to make the documents available for viewing online. Is it possible to import Word documents in these wikis ?

[Edit : what I meant about the format mess is that wiki solutions I've looked at are nowhere near MS Word in terms of styling capabilities. With Word you can actually select a bunch of headlines and change them all at once, view your outline separatly as in a 2 pane outline, move the outline around, assign styles to shortcut keys,  etc. I don't know any wiki able to manage formatting and style that powerfully. But I don't know all of them]
« Last Edit: May 11, 2010, 11:57 AM by Armando »

Armando

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 2,727
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #27 on: May 11, 2010, 11:54 AM »
I used a software called Chapter by Chapter to bring together many Word documents, without having to use MS Word's Master Documents. I never used it much but it coud be an option to look at.

superboyac

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 6,347
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #28 on: May 11, 2010, 12:14 PM »
I used a software called Chapter by Chapter to bring together many Word documents, without having to use MS Word's Master Documents. I never used it much but it coud be an option to look at.
I didn't know about either of these.  It sounds like chapter by chapter may be exactly what I'm looking for.  many thanks, Armando.

superboyac

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 6,347
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #29 on: May 11, 2010, 12:24 PM »
Armando, I also just read your long post about styles on the previous page.  Thank you.  That is good advice, and I'll be trying it out with this project.

I just spoke with our organization's top guy about this, and it's pretty serious.  I need to get this done.  They don't care about what I'm doing with the technology, but politically speaking, the heat is on.  As far as the technology, I want to make sure i don't corner myself by not organizing it well, or by not keeping track of changes made, or committing to a style and finding out that the managers want something else and having that become a big headache.  I have to do this the right way.  Maximum efficiency, as much "undo" capabilities as possible, integrated/linked solutions for page numbering, sections, TOC, etc.

All that has been done so far is very basic Word editing.  And the content is all there already.  So I'm stuck with something that is almost already complete.  Ideally, I'm looking for tools and/or methods that will allow me to do as much batch editing and modifying as possible.

Armando

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 2,727
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #30 on: May 11, 2010, 12:35 PM »
Armando, I also just read your long post about styles on the previous page.  Thank you.  That is good advice, and I'll be trying it out with this project.

I just spoke with our organization's top guy about this, and it's pretty serious.  I need to get this done.  They don't care about what I'm doing with the technology, but politically speaking, the heat is on.  As far as the technology, I want to make sure i don't corner myself by not organizing it well, or by not keeping track of changes made, or committing to a style and finding out that the managers want something else and having that become a big headache.  I have to do this the right way.  Maximum efficiency, as much "undo" capabilities as possible, integrated/linked solutions for page numbering, sections, TOC, etc.

All that has been done so far is very basic Word editing.  And the content is all there already.  So I'm stuck with something that is almost already complete.  Ideally, I'm looking for tools and/or methods that will allow me to do as much batch editing and modifying as possible.

AFAICT, apart from latex, it's MS Word (or maybe OOo or textmaker) that's the best tool for that. That's what all the PhD students here use for their thesis, technical documents, etc. Ask Darwin, maybe he'd have other ideas though.

1-Use Word since that's what you're using and it's good.
2-build your styles wisely (be rigorous about NOT formatting by hand but always using styles for everything that's formatted in special ways (titles, body, references, notes, etc. : when you do that (apart from italics and bold in the body), formatting is a breeze and any formatting can always be changed globally... Which is of course easier to do if it's one long document than several pieces put together)) ,
3-and use a backup/versioning software like DropBox or file hamster... and you're set.


The link for chapter by chapter : http://pagesperso-or...bastien.berthet/cbc/

Carol Haynes

  • Waffles for England (patent pending)
  • Global Moderator
  • Joined in 2005
  • *****
  • Posts: 8,066
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #31 on: May 11, 2010, 12:37 PM »
How about InfohesiveEP

Its designed for documentation projects that can be output in different formats. For example the same source document can be used to produce windows help files and PDF manuals.

Royalty-free distribution of InfoHesive publications: Windows eBook, PDF, HTML, CHM Help File, RTF & more.

superboyac

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 6,347
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #32 on: May 11, 2010, 12:40 PM »
Thanks Armando.  I've noted the bold part, and will adopt that strategy.  I've never used styles before, but I've always known it's the right way to do things.  I haven't used them because I've never sat down to set up my own styles; and when I've attempted, i've become frustrated.  but my frustration is more with ordered/unordered lists, than with styles in general.

I just set up AutoVer to keep versioned backups.  I'm ready to dive in now.

Armando

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 2,727
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #33 on: May 11, 2010, 12:41 PM »
One last word. I'd probably use one big document if I was you. It's bigger but easier to manage (especially if you have less than 6 y old computer), and the Map View makes the navigation a breeze once you set your styles and linked them to outline levels.

Experiment with styles and levels a bit first in a short document and use the map view or the outline view, you'll see what I mean. (I personally don't use the outline view too often, but I ALWAYS use the map view... Word would be useless to me if it didn't have that and I'd use something else. OOo has a good map view too. I think TextMAker also. But theirs aren,t as flexible IIRC)

superboyac

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 6,347
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #34 on: May 11, 2010, 12:49 PM »
Hmmm...one big document, you say?  OK, I'll give that a shot.  Personally, that feels better to me.  And I have to learn about this Map View.  Thanks again.

JavaJones

  • Review 2.0 Designer
  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 2,739
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #35 on: May 11, 2010, 12:53 PM »
Knowing now that you already have the majority of your content, and it is (presumably) largely unformatted, I think you're actually in a pretty good position. You can look through the doc as a whole, determine what styling elements are needed, then create them and use them exclusively. As others have said, don't ever use any custom styling just by manually changing font sizes or anything - always use defined and saved styles - and you should be in good shape. The trick of course is creating all those styles in the first place. Editing header and other stand-alone(ish) styles is fairly painless, but creating full bullet list indentation format sets is tedious. However you shouldn't need to do that more than once or twice, after which you can just use that formatting throughout the document, and it should end up less painless than doing it all manually as you go through.

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.  ;D

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.

I have recently come to the same conclusion, with a similar level of "pain" involved in the realization. ;) The lack of a *good* print output option is very frustrating. Surely this is a hole in the market just waiting to be filled...

- Oshyan
« Last Edit: May 11, 2010, 12:59 PM by JavaJones »

katykaty

  • Supporting Member
  • Joined in 2006
  • **
  • Posts: 224
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #36 on: May 11, 2010, 01:45 PM »
Create the styles in a blank document first, then go to the outliner and create the content there. Either type or bring in using Paste/Special/Unformatted text.

Keep formatting and content creation completely separate.

JavaJones

  • Review 2.0 Designer
  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 2,739
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #37 on: May 11, 2010, 02:26 PM »
That sounds like a royal pain. I don't doubt you may be right that "keeping formatting and content creation completely separate" is the "correct" way to do it, I wonder in this instance what exactly is gained? I've had the "pleasure" of trying to move/copy styles from one document to another in Office and it's not fun.

- Oshyan

Armando

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 2,727
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #38 on: May 11, 2010, 04:42 PM »
When formatting gets messy, it's always possible to select the messy part, and "clear formatting" (ctrl-f1 --> Styles and formatting --> Clear formatting).

Instructions in the link provided are good and I basically do the same thing.


Create the styles in a blank document first, then go to the outliner and create the content there. Either type or bring in using Paste/Special/Unformatted text.

Keep formatting and content creation completely separate.

Keeping content and formatting separate is not always convenient. I often find that formatting is a great help when structuring a document, especially when it's fairly big (e.g. : more than 50 p.).

The key is to define styles before applying any formatting, and be very rigorous in applying them whenever something needs to be formatted in a special way.

Armando

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 2,727
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #39 on: May 11, 2010, 05:43 PM »
(BTW, Carol's suggestion -- infohesiveEP -- could be an interesting avenue too.)

superboyac

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 6,347
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #40 on: May 11, 2010, 05:55 PM »
(BTW, Carol's suggestion -- infohesiveEP -- could be an interesting avenue too.)
yes, it seems nice.  but I just spoke with a couple of people, and we are not interested in exploring additional software right now.  it's a sensitive topic currently.  When I am more established here in about a year or so, I think things will be different.

Jabberwock

  • Participant
  • Joined in 2006
  • *
  • default avatar
  • Posts: 76
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #41 on: May 12, 2010, 03:41 AM »
Do not underestimate the power of Word... I admit that it is a pain in the ass in the beginning, but once you get the hang of it you can do wonders with it.

My experience does not cover 2007, but with 2003 I did some really big stuff (like laying out a scientific book). While I would always prefer a DTP package (which then I used normally), I would certainly stick with Word than learn a new system (like laTEX) from scratch.

Some notes: be very disciplined while using styles. Try to use manual formatting only for "local" (i.e. inline) formatting. Whenever some properties are to be shared among several passages, paragraphs etc., use styles (even for text formatting). This will save you a lot of headaches later.

I am not sure I get the question about styles based on paragraphs. In 2003 when you select "New Style", you will see several things:
- the style it is supposed to be based on
- the manual overrides that were made to that paragraph (if it is a paragraph style).

For example, I select a Normal paragraph, make it a bullet and change the font to Arial 12 (Normal is Times New Roman 10). Then I use "New Style" and I see in the dialog:
- style based on Normal (this can be changed)
- description of the styling i.e. : Normal + bullet list + Font Arial 12.

That's what my new style would be - all properties of Normal plus the two changes.

But what if I don't want the font change reflected in the style, just the bullets?

In the dialog select "Formatting" and change it to the font that was default for the base style, i.e. Times New Roman 10. You will see that the style description is now:
- Normal + bullet list

Similarly, if I want to add some more formatting to the style, I just use the dialog to manipulate the properties. This is very powerful, I suggest you at least go over the options to see what can be assigned at the paragraph level.

Make sure that once you have the style, you modify it manually and not update it based on the paragraph you are in - you never know what might go in there (i.e. how it differs from the style it is based on).

As whether to format on the go or to write plain text and format later, this is a matter of personal preference. I did the latter, but mostly because I worked with content provided by other authors - if I wrote the stuff from scratch, I would style it immediately.

Finally, I would go with a single file, unless the document is very large or contains many heavy graphics (but I suppose today's computers can handle that, too - mine is yesterday's...).

Edit: *big facepalm* I did not read the second page of the thread - most of my suggestions were mentioned earlier... Sorry about that!
« Last Edit: May 12, 2010, 03:44 AM by Jabberwock »

superboyac

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 6,347
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #42 on: May 12, 2010, 08:38 AM »
Thank you Jabberwock.  Those are useful instructions and I found them helpful.

Armando

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 2,727
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #43 on: May 12, 2010, 08:38 PM »
And it confirms what others have said !  :)
Yes, never underestimate What can Word and other office products can do...

40hz

  • Supporting Member
  • Joined in 2007
  • **
  • Posts: 11,857
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #44 on: May 12, 2010, 09:32 PM »
@Armando - thanks for the heads-up on Chapter by Chapter.  :Thmbsup:

Very neat little Word utility. Never heard of it until your post. I downloaded and started playing with it a bit. I'm quite impressed already.

And here I thought I knew them all... ;D

CxC in combination with AutoVer (for version control) could be just what I need for a new book project I'm soon to be involved in.



« Last Edit: May 12, 2010, 09:39 PM by 40hz »

Armando

  • Charter Member
  • Joined in 2005
  • ***
  • Posts: 2,727
    • View Profile
    • Donate to Member
Re: Instruction manual creation recommendations?
« Reply #45 on: May 12, 2010, 09:48 PM »
@Armando - thanks for the heads-up on Chapter by Chapter:Thmbsup:

Very neat little Word utility. Never heard of it until your post. I downloaded and started playing with it a bit. I'm quite impressed already.

And here I thought I knew them all... ;D

CxC in combination with AutoVer (for version control) could be just what I need for a new book project I'm soon to be involved in.

You're welcome.
Yes, it's pretty good. Especially if you don't like having everything in the same file. Sometimes it helps to split things up (performance wise and also in terms of "creation" -- not having to look at all your material every time you open the doc can help avoid unnecessary perfectionism or procrastination).
However, I think I prefer having everything in the same document... after all easier to have an overall picture, etc. + word can open several windows of the same document which makes working on many chapters at once a breeze.