TechWhirl (TECHWR-L) is a resource for technical writing and technical communications professionals of all experience levels and in all industries to share their experiences and acquire information.
For two decades, technical communicators have turned to TechWhirl to ask and answer questions about the always-changing world of technical communications, such as tools, skills, career paths, methodologies, and emerging industries. The TechWhirl Archives and magazine, created for, by and about technical writers, offer a wealth of knowledge to everyone with an interest in any aspect of technical communications.
> [snip] We're
> developing a *new* type of product
> [...more snips...]
> -- rather like a computer network -- so there are many
> pieces that will be operated by different individuals
> within the company. Some people will have higher "security
> clearances" than others and will be able to perform tasks
> for which others should not even receive instructions.
Situations like this make me think on bad days that most of the work I've done
over the last 10 years is worthless, and on good days that most of the work
I've done over the last 10 years has been preparing to exploit emerging (oh
hopeful word) technology and write something useful.
I'm guessing that Karen's product has some or all of the following
1. Some functions must be used by everyone, regardless of security clearance.
2. Some functions can be used by anyone, regardless of security clearance.
3. Some secure tasks incorporate other, less secure, tasks.
4. Some secure tasks are to do with settings and maintenance of the product.
5. Some secure tasks are to do with business responsibilities in the user
6. User sites can specify the clearance required to access secure functions or
perform secure tasks.
7. The product has a core module with additional modules that can be installed
in many different combinations.
8. User sites can implement different degrees of complexity and security in
whatever combinations of modules they buy.
9. "User sites" can consist of multiple sites. A customer company might
implement different degrees of complexity and security at its different sites.
Now, if any of those conditions are true, how can the software manufacturer
produce manuals which give each user instructions relevant to his or her tasks,
and no more? I don't think it can be done, because I don't think the software
manufacturer can know how the customer companies allocate tasks to users.
The best I can think of is to provide manuals for each "security clearance",
with lots of duplication so that users don't have to go bouncing around between
manuals. That would probably work if the user sites can't specify the
relationships between functions and clearances.
But if users control who can access what function?
Well that's why I've come to believe that I was kidding myself when I thought I
was writing "task-oriented documentation" for a highly tailorable software
That's why I think that documenting software packages must often be just
function-oriented documentation on a larger scale. That doesn't mean the doco
has to revert to describing the system from the inside out. But it does mean
that the organising principle for manuals must be dictated by the software, not
by our guesses at how the software is going to be used.
BUT, with online documentation (including EPSS, wizards, help, whatever..),
there's a chance of really tailoring the documentation to the individual users.
The software has to know each user's security clearance. If the software and
the documentation developers can work together, it should be possible for the
software to call different pieces of documentation for each clearance.
I've never had the chance to implement a system like this. Is there someone out
there who has? My feeling is that such a system needs to be designed as part of
the software and the software interface. Has anyone been able to do it that
way? Any other way? And how did you:
* Organise and classify the online documents? Document pieces?
* Manage communications between the documentation and the software teams?
* Test everything???
(hoping for some really good bedtime stories)
scharker -at- ozemail -dot- com -dot- au
** Never express yourself more
** clearly than you can think
** ... Nils Bohr