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.
Re: Uniform processes and designs through an editorial guide
Subject:Re: Uniform processes and designs through an editorial guide From:"Riese, Claudia" <CRiese -at- tunstall -dot- de> To:"'techwr-l -at- lists -dot- techwr-l -dot- com'" <techwr-l -at- lists -dot- techwr-l -dot- com> Date:Wed, 17 Feb 2021 11:35:56 +0000
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
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
