Guidelines how to write a manual

This forum is for the discussion of the business and craft of writing help. For example writing style, choices of HTML Help or WinHelp or browser-based and so on...

Moderators: Alexander Halser, Tim Green

Post Reply
HpW
Posts: 31
Joined: Thu Nov 18, 2004 11:50 pm

Guidelines how to write a manual

Unread post by HpW »

Hi,

are there any guidelines book's or online stuff for best practic's to write and structure a "Software Help Manual". In other words help authoring related practic's issues (it is not a tool related question)!

Cheers

hpw
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Unread post by Tim Green »

I just delivered a talk on this at the European Shareware Conference in Strasbourg at the beginning of this month. I'm working on an online version that I am going to post on my website as soon as it's ready but until then you can download the PowerPoint presentation here:

http://www.helpandmanual.com/eswc/

My presentation is "betterhelp.zip". This is actually the longer version of the talk -- I only had half an hour at the conference so I had to deliver a shorter version. If you open it in edit mode in PowerPoint you can see the speaker's notes, which are a lot more detailed than the texts on the screen. I also have a version with spoken narration included but that's around 13MB so I didn't want to post it for general download as I figured that most people would prefer to get the smaller file.

You can also download Alex Halser's presentation on the technical aspects of integrating help with your project on the same page.
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
charlotte
Posts: 2
Joined: Fri Mar 18, 2011 7:34 am

Re: Guidelines how to write a manual

Unread post by charlotte »

Hi Tim

The URL did not lead me to find the referenced presentations - could you please give me an updated URL?

Thank you
Charlotte
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Guidelines how to write a manual

Unread post by Tim Green »

Hi Charlotte,

This old presentation is really out of date now, that was 2004 and it is no longer available. :?
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Bob Roos
Posts: 11
Joined: Tue Jan 31, 2012 12:51 am

Re: Guidelines how to write a manual

Unread post by Bob Roos »

I think this may have been the answer to my as yet unasked question.

I am writing the 2nd version of a product and the help in the first version was hit and miss (mostly the latter). I want to do a more organized job and have consistency between the sections. I just don't know where to start. I was looking for a template/sample/project of some kind that had sections and a TOC and index built in to it that could be a starting point.

I have screens in the project that need explaining and I have 5 programming classes that need explaining with the members and methods that belong to them. These have no screens. It is name and parameters and then explaining each of the parameters. I would love to see an example of a good way to present them. I come from a background of reading tons of IBM mainframe manuals over the last 40 years.

I am good at taking something extant and changing it to what I need, but not good at all starting with a blank slate. So for me the task is to find that good starting point. Do you have any suggestions?

Also were there any timeless gems in that presentation? Cars have changed tremendously over the years, but there are still some very basic things about driving that pertain.

Thanks, Bob Roos
User avatar
Tim Green
Site Admin
Posts: 23156
Joined: Mon Jun 24, 2002 9:11 am
Location: Bruehl, Germany
Contact:

Re: Guidelines how to write a manual

Unread post by Tim Green »

Hi Bob,

To be honest, I can hardly remember what was in the presentation any more; I think it's stored on a 5 1/4" floppy somewhere along with my old Apricot and Kaypro CP/M manuals... ;-) A couple of the things I did emphasize was use white space, use illustrations and try to make your users smile regularly. However, we have lots of people on the forum faced with problems like this and I'm sure they will chime in with helpful suggestions.

One thing that is often helpful is to have a clear idea of who you are writing for, in terms of what they already know and what they are not likely to know so that you will have to explain it to them. If you can find someone who matches that profile and then try to explain the product to them you can learn a lot.

On programming components: Examples, examples, examples. The biggest weakness of all programming component documentation is the tendency to explain at length and forget about examples. A couple of good, simple examples usually makes things clear immediately where a long explanation just makes my eyes glaze over. (MSDN is particularly bad that way, I usually only ever go there as a last resort because of that.)
Regards,
Tim (EC Software Documentation & User Support)

Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Post Reply