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
Guidelines how to write a manual
Moderators: Alexander Halser, Tim Green
- Tim Green
- Site Admin
- Posts: 23183
- Joined: Mon Jun 24, 2002 9:11 am
- Location: Bruehl, Germany
- Contact:
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.
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.
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Re: Guidelines how to write a manual
Hi Tim
The URL did not lead me to find the referenced presentations - could you please give me an updated URL?
Thank you
Charlotte
The URL did not lead me to find the referenced presentations - could you please give me an updated URL?
Thank you
Charlotte
- Tim Green
- Site Admin
- Posts: 23183
- Joined: Mon Jun 24, 2002 9:11 am
- Location: Bruehl, Germany
- Contact:
Re: Guidelines how to write a manual
Hi Charlotte,
This old presentation is really out of date now, that was 2004 and it is no longer available.
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.
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.
Re: Guidelines how to write a manual
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
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
- Tim Green
- Site Admin
- Posts: 23183
- Joined: Mon Jun 24, 2002 9:11 am
- Location: Bruehl, Germany
- Contact:
Re: Guidelines how to write a manual
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.)
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.
Tim (EC Software Documentation & User Support)
Private support:
Please do not email or PM me with private support requests -- post to the forum directly.