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 nina -dot- barzgaran -at- barzgaran -dot- at -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
--
Nina Barzgaran, M.A.
Technical Communicator
Linzer Strasse 434-436/3/23
1140 Wien
AUSTRIA
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
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
References:
Re: Uniform processes and designs through an editorial guide: From: Riese, Claudia
Previous by Author:
conventions for presenting Win and Mac keyboard shortcuts?
Next by Author:
Uniform processes and designs through an editorial guide
Previous by Thread:
RE: Uniform processes and designs through an editorial guide
Next by Thread:
Re: Uniform processes and designs through an editorial guide
Search our Technical Writing Archives & Magazine
Visit TechWhirl's Other Sites
Sponsored Ads