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 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
Documenting the ever-changing Windows environment...
Moderators: Alexander Halser, Tim Green
- Sheri Steeves
- Posts: 146
- Joined: Tue Aug 05, 2008 5:06 pm
- Location: Ottawa, Ontario,CANADA
- Contact:
- Tim Green
- Site Admin
- Posts: 23189
- Joined: Mon Jun 24, 2002 9:11 am
- Location: Bruehl, Germany
- Contact:
Re: Documenting the ever-changing Windows environment...
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...
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.
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...
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.
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.
- Alexander Hompe
- Posts: 182
- Joined: Mon Mar 20, 2006 9:01 am
- Location: Germany
Re: Documenting the ever-changing Windows environment...
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
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
Windows 7 Ultimate 64bit
Re: Documenting the ever-changing Windows environment...
Are you being paid by Microsoft? I would just say, "Change your printer (refer to the operating system help)"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.
My 2 cents,
Roy
Re: Documenting the ever-changing Windows environment...
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
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
- Sheri Steeves
- Posts: 146
- Joined: Tue Aug 05, 2008 5:06 pm
- Location: Ottawa, Ontario,CANADA
- Contact:
Re: Documenting the ever-changing Windows environment...
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.
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.
Re: Documenting the ever-changing Windows environment...
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.