Re: Advice on structuring a Help File

[DGoldstein -at- DeusTech -dot- com]

Hi Nadine,

Sorry no one's answered until now. Also sorry that for now, I only have questions rather than answers:

1. What is the format of your "online release notes"? Is this an unformatted Readme.txt file, some other formatted file, or true online Help (e.g. HTML-based, WinHelp, etc.)?

2. Is there a technical reason why you have Section 2 as a "single page with just the heading on"? This seems difficult for the online user, unless we are talking about a true online Help file, in which case I assume that there are links on that page (topic) as well.

3. Is your "Section 2: Set-Up Instructions" the equivalent of the developers' "[Section] 4. Set-Up Requirements"? If so, why the title change? If not, where did you put the requirements?

Regarding your question about setup instructions: Until you answer the above, I'm just shooting in the dark, but it seems to me that the developers might have gotten it right to begin with. If only some of the items require setting up, it might be easier for the user to have each list of items contiguous with its setup instructions, rather than in separate sections. Of course, if this is a true online Help file, then the lists will have hyperlinks for those items that have setup instructions.

Dan Goldstein 

<snip> I am in the process of creating on-line release notes for a software
> application release and need some advice. The developers have structured the
> release notes as below:
> Title 
> 1. Overview of Contents (what the software change is)
> 2. Accessing the Functionality (how to find it in the system)
> 3. User Instructions (what the user should do when they have found it)
> 4. Set-Up Requirements (single title)
> 4a. Programs (list of programs which need setting up - sometimes with
> instructions on how to do it)
> 4b. Parameters (list of parameters which need setting up - sometimes with
> instructions on how to do it)
> 4c. Batch Programs (list of batch programs which need setting up - sometimes
> with instructions on how to do it)
> I have structured my help file as follows:
> Chapter: Title and then the overview on the same page - obvious
> Section 1: User Instructions - 1 page incorporating "Accessing the
> Functionality" and "User Instructions" as they follow on from each other and
> are one of the same thing - they are also what the 'user' needs to know
> Section 2: Set-Up Instructions - single page with just the heading on
> Section 2a - Programs - as their 4a
> Section 2b - Parameters - as their 4b
> Section 2c - Batch Programs - as their 4c
> Now the question is - where do I put the set-up instructions?</snip>
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

ANNOUNCING ROBOHELP STUDIO

RoboHelp Studio maximizes your Help authoring power by combining 
RoboHelp Office and RoboDemo, so you can easily create professional 
Help systems that feature interactive tutorials and demos.

Find out more about RoboHelp Studio at http://www.ehelp.com/techwr-l2

---
You are currently subscribed to techwr-l as:
archive -at- raycomm -dot- com
To unsubscribe send a blank email to leave-techwr-l-obscured -at- lists -dot- raycomm -dot- com
Send administrative questions to ejray -at- raycomm -dot- com -dot-  Visit
http://www.raycomm.com/techwhirl/ for more resources and info.