Documenting the ever-changing Windows environment...

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
User avatar
Sheri Steeves
Posts: 146
Joined: Tue Aug 05, 2008 5:06 pm
Location: Ottawa, Ontario,CANADA
Contact:

Documenting the ever-changing Windows environment...

Unread post by Sheri Steeves »

Hello,

I'm looking for feedback on how other documentation writes have handled this scenario. I'm a techie (programmer) who gets to write documentation. Windows in its infinite wisdom :wink: keeps changing the names of things like the My Documents folder and the Printers and Faxes folder in each new version of the operating system.

How do you normally approach this? For instance, in several places in my docs, I have to direct the user to the Printers and Faxes folder, which is "Devices and Printers" on Windows 7, and in Vista often not even on the Start menu - you have to go through the Control Panel unless you have added it to the Start menu yourself. A general user would normally not even know this folder exists; they only see the printer in the list of printers when they print.

Should I include complete instructions for each operating system? That could work for the Printers and Faxes folder, but what about when I want to refer the use to the My Documents folder, for XP, which became Documents on Vista and Windows 7. Writing something like " can be found in your My Documents folder ( Documents on Windows VIsta or Windows 7)... becomes cumbersome and hard to read.

Any thoughts? How have others handled this in their documentation?

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

Re: Documenting the ever-changing Windows environment...

Unread post by Tim Green »

Hi Sheri,

I hear you. I find this very annoying as well, and it gets even worse when you get into unnecessary terminology and position changes in dialogs. Try explaining how to change the Windows system locale without knowing what version of Windows someone is using, for example... :evil:

In correspondence, I've taken to saying "your Documents directory" and leaving it at that, and everyone seems to understand this. I think you can do this without additional explanation if you're documenting a program aimed at relatively experienced users. If you're talking to complete beginners you probably need to spell it out and refer to the differences between the Windows versions.

I've also started referring to the main folders as "directories" and anything inside them as "folders". This distinction is artificial, but users seem to understand it intuitively. For example, I refer to the "Program Files directory" and also the "Help & Manual program directory", and I would then refer to the folders inside those directories as "folders". Again, this seems to work, although I'm sure it would be possible to weigh the beans and say it's not strictly correct. However, I've come to the conclusion that the truth is what works. 8)
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.
User avatar
Alexander Hompe
Posts: 182
Joined: Mon Mar 20, 2006 9:01 am
Location: Germany

Re: Documenting the ever-changing Windows environment...

Unread post by Alexander Hompe »

Hi Sheri,

when it is an option to hand out one separate document for each windows version, you could use conditions and different builds "XP", "Vista", "W7".
More comfortable, when there are many repetitions: skins where you define variables.
Example: <%dir_documents%>
skin_xp.xml: <%dir_documents%>=My documents
skin_w7.xml: <%dir_documents%>=Documents

Skins are not comfortable when you have to describe completely different procedures depending on the windows version.
Maybe a mix of conditional builds and 'variable skins'?

I have written an installation guideline in German and from W7 I additionally have to decide whether I refer to the folder names that the user see ("Bibliotheken > Dokumente > Eigene Dokumente") or to the internal name that often is necessary when you have to select a folder in an installation wizard ("C:\Users\Username\Documents"). In english this shouldn't be a problem, I guess.

Regards,
Alex
Help & Manual 6 Professional Edition
Windows 7 Ultimate 64bit
Roy Henry
Posts: 47
Joined: Fri Sep 24, 2004 10:24 pm
Location: Alberta, Canada

Re: Documenting the ever-changing Windows environment...

Unread post by Roy Henry »

Sheri Steeves wrote:
For instance, in several places in my docs, I have to direct the user to the Printers and Faxes folder, which is "Devices and Printers" on Windows 7, and in Vista often not even on the Start menu - you have to go through the Control Panel unless you have added it to the Start menu yourself. A general user would normally not even know this folder exists; they only see the printer in the list of printers when they print.
Are you being paid by Microsoft? I would just say, "Change your printer (refer to the operating system help)"

My 2 cents,
Roy
User avatar
Winsteps
Posts: 443
Joined: Wed Aug 29, 2007 7:34 am

Re: Documenting the ever-changing Windows environment...

Unread post by Winsteps »

Roy, please try this experiment:

Imagine you are an end-user
Launch operating system Help (if you know how)
In the Help search box, type "Change my printer"

For me (Windows XP), Microsoft returned these 4 documents:
1. Glossary
2. What's New in Microsoft Windows XP Service Pack 2 (SP2): Frequently Asked Questions
3. Put a shortcut on the desktop
4. Sharing files and folders overview

OK - so what do I do now?

Roy, don't you find it is tough enough persuading end-users to read your Help pages? Getting them to read Microsoft's is close to impossible :cry:
User avatar
Sheri Steeves
Posts: 146
Joined: Tue Aug 05, 2008 5:06 pm
Location: Ottawa, Ontario,CANADA
Contact:

Re: Documenting the ever-changing Windows environment...

Unread post by Sheri Steeves »

I agree with Tim and Winsteps. If I was targetting a more experience audience I wouldn't have to explain everything out but I know how varied a range of user's we have from also handling telephone support. Let me tell you on-line desktop sharing is the best thing for tech support, and screen grabs are the next best thing.

I ended up adding a topic on how to find your printer and refering to that from the different sections, and following Tim's example for the Documents folder.
Roy Henry
Posts: 47
Joined: Fri Sep 24, 2004 10:24 pm
Location: Alberta, Canada

Re: Documenting the ever-changing Windows environment...

Unread post by Roy Henry »

The first rule of documentation is probably "know your audience". You have to decide where to draw the line in terms of how detailed your instructions are. Do you tell them how to use a mouse? Do you tell them how to get on the internet? Do you tell them how to change their printer? If your company is paying the support costs for calls on how to change printers, go ahead and put it in the help. I'm just saying that, at the company I work for, we assume a certain level of user proficiency and do not tell them things we might have 15 years ago when more users where novices.
Post Reply