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.
The first thing that came to mind was the statement attributed
to Marie Antoinette on being told "Your Majesty, the users have
no procedures to read", to which she replied "Let them read CASE".
Seriously, visual/diagrammatic methods are often the simplest to explain
complex systems, provided you understand the language. However, some
types of diagram describe internal structure/organisation and not
external appearance or function. Entity relationship diagrams (objects,
classes etc) are often in this category.
Other types of diagrams which may be more useful are:
* Data flow diagrams
* Procedural hierarchies
* Organisational diagrams
* State diagrams
* Architecture diagrams
A few suggestions and possibilities:
* Create or use additional relevant diagrams so that:
- the writers can understand the product
- the diagrams can be used in the final docs
- SW developers can better understand the product (gasp!)
> Our products are very complex, and involve myriad
> customer-administrable, configurable elements
It must therefore have possibly hierarchical relationships which
can be described, and defined configuration procedures.
* Involve the writers in GUI/functionality design and review alongside
the software developers. This way they are familiar "the latest"
product and can help design it from a user perpective.
* Appoint one writer to get their head right around the whole product
so they can clearly explain the big picture and what it is for.
* Prepare template procedures containing object classes, then
import or copy the appropriate instance data when the GUI is complete.
Your CASE and publishing tools will determine the difficult of importing.