Help formatting conventions

[SueBK]

I am currently writing both a user guide and a technical manual for our monster database. The user guide relies extensively on screen dumps as its a step-by-step "this is how you do it" deal. I've been told to make the technical manual more "geek level".

I'm wondering if there's any standard formatting conventions people use when writing manuals/guides? For example: in the user guide I started using images of buttons, but eventually that got a bit unwieldly, so I've typed the exact words of the button and added a border and a grey background. Which makes it look kinda 'button like'.

In the technical manual, I need to constantly reference database elements (tables, queries etc). I'd like somehow to distinquish these from the rest of my text. I was thinking of writing them as [ThisIsATable], but of course [ ] are fields in VB, and I don't want to confuse the truly geek.

Any suggestions?

 

[wazz]

you could take a microsoft-like approach by opening any office app, typing a question for help and checking out the answer. you'll see that certain things are bold, some are hyperlinks, some are italicized, etc. for the technical doc, copy the formatting from the help file that goes with the vb editor.

otherwise, open any user-friendly app, maybe one that's already used (and liked) in your office, and copy its help file's formatting/approach.

 

[wazz]

you could also go all out and create a .chm file. search your computer for any/all .chm files and open them up and have a look. you probably use them all the time. the software to make that type of file is free. there's a learning curve that you might not want to deal with though. it's a bit annoying at first but after a while you get the hang of it. the beauty part is that all the help pages are basically (or can be) html pages and you can apply styles. ironically, it could use a better help file.