RE: Uniform processes and designs through an editorial guide

["James Byrne" <jbyrne -at- maine -dot- rr -dot- com>]

Keeping a record of the current status: Your approach worked for us.  About
25 years ago I was part of a couple of similar standardization efforts,
although it does not sound like your project is as extreme as ours was at
the time, so hopefully your effort will go more smoothly.  Our efforts were
to standardize processes for several US Navy facilities spread across the
entire US.  One of the first things we did was to collect written processes
(within the scope of the effort) from all facilities.  We then organized
them in tables so that it was clear how each facility performed each process
and what could be standardized.  This also highlighted those things which
could not be standardized and allowed each local facility to have a clear
understanding of how they would have to modify these "leftover" processes to
integrate with the new corporate standards, as well as identify areas for
future corporate standardization.

Pitfalls: The most difficult and expensive parts of our effort was when
processes depended heavily on differences in facility organizational
structure and skill mixtures, available material
assets/machinery/computers/tools, and local businesses to which the facility
has outsourced processes when the facility did not have the necessary
in-house skill set, to name a couple.  It is one thing to provide a standard
outline on how to write a document.  It is quite another to tell the writer
that he/she will have to use a Mac instead of a PC, AND they will have to
PAY for a bunch of Macs and a bunch of HP printers that can support the new
font requirements, and some of the things that the writer used to do will
now be done by others (and NEITHER party will be happy with THAT change,
believe me).  And training.  Don't forget training when some of the changes
require it.  Things like these ended up being a substantial fraction of the
"leftover" processes in my Navy project, and some local processes are still
separate from the corporate standard.  

If you find you have some of these problems, you will need to have
high-level corporate AND local management support for this effort; it cannot
be just the brain child of one person/group that happens to have some
current visibility, else it is doomed.  

I believe it was Winston Churchill who said "You can depend upon the
Americans to do the right thing. But only after they have exhausted every
other possibility."  You can probably fill in the nationality to suit the
situation...

Jim Byrne

-----Original Message-----
From: techwr-l-bounces+jbyrne=maine -dot- rr -dot- com -at- lists -dot- techwr-l -dot- com
<techwr-l-bounces+jbyrne=maine -dot- rr -dot- com -at- lists -dot- techwr-l -dot- com> On Behalf Of
Riese, Claudia
Sent: Wednesday, February 17, 2021 6:36 AM
To: 'techwr-l -at- lists -dot- techwr-l -dot- com' <techwr-l -at- lists -dot- techwr-l -dot- com>
Subject: Re: Uniform processes and designs through an editorial guide

Hi all,

What a surprise. I just  subscribed to the mailing list yesterday and wrote
my first question. Immediately I received several detailed answers. Thank
you! This is very helpful. 
You have given me a lot of impulses. I'll post here some of the things that
are on my mind.

Technical Writer's Guide:
Of the terms you suggested, I like "Technical Writer's Guide" the best. Like
with Robert, the "Style Guide" section will be just one topic among others.
I envision that the Technical Writer's Guide will cover the following
topics:
- Processes in the day-to-day work of the technical writer.
- Layout guidelines
- Writing rules
-Tools
Or do you prefer "Editorial Guide" when you read this list?

Keeping a record of the current status:
Because the technical writers are only at the beginning of the cooperation,
I would first write down the current status for each topic at each location
(country). Then everyone can see how what is being done at which location.
Only in the next step will we discuss what can be standardised. Paul writes
very nicely how lengthy and difficult it can be to find uniform ways.
(Paul, We have one thing in common: 26 years as Technical Writer on
01/09/2021!) Can you understand this approach? Or would you not write down
the description of the current status in the Technical Writer's Guide? Where
else would you write it down? It would have to be a place accessible to all
technical writers.

Processes:
There are various processes in the daily life of technical writers. I would
like to write down these processes in the Technical Writer's guide.
It is very important to me how the approval process works. Who checks the
documents? How is the approval documented? How is it ensured that the
document is ready for the market together with the product?
How will the Technical writer be informed about bugs or change requests in a
document?
What does the technical writer have to do if a document has to be translated
into foreign languages? Who is the contact person for an external
translation agency?
Who puts the document online on the company's homepage? Who commissions a
printer?
These are actually all questions that a new employee would ask. After all, a
new colleague is also a target group for the Technical Writer's Guide.
In your answers to my question, the "processes" section is not so relevant.
Where are your processes documented? Are there other documents for this? In
your opinion, do processes not belong in a Writer's Guide?

Wiki:
Sharon, the technical writers do not currently work with the same software.
FrameMaker, InDesign, Word and other tools are in use. To me, a wiki still
seems to be the best solution. Confluence and other tools are in use at some
of the company's locations. The technical writers could set up an area
there. Are there any other ideas?

Layout guidelines:
Layout guidelines seem to be a central element of the Technical Writer's
Guideline for all of you. To me, this is a style guide. Many companies have
a style guide for marketing documents. You can find examples of these on the
internet. Lin sent a link where you can find examples. Often the technical
documentation is forgotten in this style guide. 
For me, the style guide is part of the Technical Writer's Guidelines. 
As Lin writes, I would also include, for example:
- Brand consistency rules like logo placement
- Color palette information and codes (hex or RGB) for text, bullets, and
other design elements
- Font styles and rules for usage
- Rules of use (like using half of a page with an image and using certain
fonts and which sizes for text on the other side)


Writing rules
Several of you mention the writing rules. For me, too, they belong in a
Technical Writer's Guide. But the writing rules depend on the language. The
writing rules you mention refer to English. The technical writers for whom I
write write in their own language. And there the rules differ from English.
So I'll postpone this topic for now.

Tools
The technical writers currently use very different software (FrameMaker,
InDesign, Word etc.). I find it very difficult to standardise the tools
because there is a lot of existing documentation at each location that was
created with a certain software tool. It is easy for the creation of
templates etc. if everyone works with the same software. But the reader of
the documentation will not notice that different software was used for the
same layout. What is your experience with switching to a common software?

Best regards
Claudia



-----Ursprüngliche Nachricht-----
Von: techwr-l-bounces+criese=tunstall -dot- de -at- lists -dot- techwr-l -dot- com
<techwr-l-bounces+criese=tunstall -dot- de -at- lists -dot- techwr-l -dot- com> Im Auftrag von
Robert Lauriston
Gesendet: Mittwoch, 17. Februar 2021 00:00
An: TECHWR-L <techwr-l -at- techwr-l -dot- com>
Betreff: Re: Uniform processes and designs through an editorial guide

"Editorial Guide" is a good title. The one I wrote was called "Technical
Writer's Guide." The table of contents gives a good idea of what it covered.

The Style Guide section told writers to follow the Microsoft Manual of Style
for Technical Publication and listed some exceptions we had to those
standards.

MIF2Go was a FrameMaker add-on for publishing online help.

   - Style Standards
      - Style Guide
      - Recognizing Trademarks and Copyrights
      - Images
      - Document Standards
         - User Guides and Installation Guides
         - Readmes
         - New Features Guides
         - Evaluation Guides
      - Software for Technical Writers
      - Authoring Tools
      - Company Applications
   - Working with FrameMaker
      - Create a New Book
      - Update a Book for a New Release
      - Text Formatting: Using Paragraph and Character Tags
         - Paragraph Tags
         - Character Tags
      - Screen Shots
      - Cross-References
         - Cross-References vs Hypertext Markers
         - Create a Cross-Reference
         - Edit a Cross-Reference
         - Find an Unresolved Cross-Reference
      - Context-Sensitive Help
         - FrameMaker Source
         - Set up context-sensitive help for a new feature in a Windows app
         - Set up context-sensitive help for a new feature in an Eclipse
         app
      - Generating PDFs
   - Working with Microsoft Word
   - Generating Online Help with MIF2Go
      - MIF2Go Tasks Common to All Formats
         - Install MIF2Go
         - Set Up Multiple Help Formats for a Single Book
      - MS HTML Help (.chm)
         - Create a New MS HTML Help (.chm) Project
         - Sample MIF2HTM.INI for MS HTML Help
      - Eclipse Help
         - Create a New Eclipse Help Project
         - Sample MIF2HTM.INI for Eclipse
      - OmniHelp (for Web-Based Applications)
         - Install the OmniHelp Control Files
         - Create a New OmniHelp Project
         - Sample MIF2HTM.INI for OmniHelp
      - Troubleshooting
   - Generating PDFs
      - PDF Setup in Acrobat Distiller
      - PDF Setup in FrameMaker
      - Generate a PDF from a FrameMaker Book
      - Generate a PDF from a Microsoft Word Document
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and
content development | https://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as CRiese -at- tunstall -dot- de -dot- 

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and
info.

Looking for articles on Technical Communications?  Head over to our online
magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public
email archives @ http://techwr-l.com/archives
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and
content development | https://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as jbyrne -at- maine -dot- rr -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and
info.

Looking for articles on Technical Communications?  Head over to our online
magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public
email archives @ http://techwr-l.com/archives

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Visit TechWhirl for the latest on content technology, content strategy and content development | https://techwhirl.com

^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot- 

To unsubscribe send a blank email to
techwr-l-leave -at- lists -dot- techwr-l -dot- com


Send administrative questions to admin -at- techwr-l -dot- com -dot-  Visit
http://www.techwhirl.com/email-discussion-groups/ for more resources and info.

Looking for articles on Technical Communications?  Head over to our online magazine at http://techwhirl.com

Looking for the archived Techwr-l email discussions?  Search our public email archives @ http://techwr-l.com/archives