Link Search Menu Expand Document
Technical Writing for Translators

Self-teaching

Reviewing existing documentation⎹ Blogs and podcasts⎹ Books⎹ Writing

Reviewing existing documentation

Begin your self-teaching with a resolution: next time you open the box of a newly-bought gadget or appliance, do what no sane person would do and actually read the manual.

While reading, pay attention to the following aspects:

  • Structure of the document at the “macro” level:
    • Table of contents
    • Division into sections and subsections (chapters and subchapters)
    • Structural separation of different types of information, e.g., into instructions (step-by-step procedures), concepts (descriptions, definitions), and reference content (datasheets, specifications)
    • Metatextual content (revision history, chapter objectives)
    • Legal notes (copyrights, regulations)
    • Glossaries, indexes, references
  • Structure of sections and pages:
    • Page layout (headers and footers, margins, alignment, page numbers, etc.)
    • Text style and formatting (font variants, headline styles, bullet lists, etc.).
  • Localization (translations and regional adjustments, e.g., correct images for country-specific types of power plugs)
  • Language style and grammar:
    • Language variety (e.g., British vs. American)
    • Grammatical correctness, punctuation, typos
    • Sentence structure (e.g., passive vs. active voice)
    • Choice of words (e.g., technical terms vs. plain language)
    • Ambiguity and redundancy (explicitness vs. cohesion)
    • Style and register
  • Visual content (pictures, icons, and captions with index numbers for images)
  • Informational value (is the content relevant and helpful?)

Assess the document by considering the following questions:

  • Are all necessary elements in place and properly structured?1
  • Is information helpful, clear, and easy to find?
  • Is the print sharp? Are images in high resolution? Is the text well translated?
  • Is information correct, up-to-date, and conforming to industry standards?
  • Can you access the content elsewhere (e.g., download the guide as a PDF)?

❗ IMPORTANT: The above framework is not an industry-approved method for documentation testing. It’s just an outline of some aspects that may contribute to overall quality of documentation.

You could use the same approach for documents published online, but with some additional, web-specific points, such as:

  • Website responsiveness: how well the website scales relative to window size on different devices?
  • Are all elements loading and being displayed correctly?
  • Are there fallbacks for fonts and alt-texts for images?
  • Is the user interface intuitive and functional (e.g., collapsible navigation and “back to top” button)?
  • Are links active and do they point to the right resources?

Once you spend some time reading documents and studying content design, you’ll develop an eye for good and bad documentation, just as you’ve learned to recognize good and bad translation. In addition to reading documentation, regularly visit tech comm blogs and follow industry trends. Revise your old work from time to time and apply newly learned best practices in your writing.

At times you might wonder: “OK, how do I know if this practice here is considered good or bad?”. This is a good sign – it shows that you have investigative qualities much desired in this field. Take any confusion as an incentive to do more research. Reach out to the community and ask professionals if you can’t find a clear answer.

Chances are there won’t be a clear answer at all, though. Trends in tech comm are changing and there will always be some conflicting views. Just think about all the disputes people have over the serial comma in English, for example. Design choices answer to users’ preferences; they aren’t necessarily objective truths. Just remember that you are a user too, so you have a say here too. I love navbars that collapse on scroll. My friend hates them. What about you?

As for reading suggestions, any documentation should do. If you’re really pressed for time, you can kill two birds with one stone: read guides for the products you use or for tools and technologies you want to learn (e.g., HTML). You can also check out professional style guides (docs on how to write docs!) like the one from Atlassian or Google.

Blogs and podcasts

These are your best bet to stay updated with industry news. Check out the blogs and podcasts linked below. They are maintained by professionals active in tech comm and related areas. You can expect quality content with lots of practical tips and real-life examples.

BLOGS:

PODCASTS:

Books

If you prefer a more traditional approach, there are books as well. Some popular titles include:

  • “Technical Communication” by Mike Markel
  • “Technical Writing 101” by Alan S. Pringle & Sarah S. O’Keefe
  • “Technical Writing for Dummies” by Sheryl Lindsell-Robert
  • “The Insider’s Guide to Technical Writing” by Krista Van Laan

❗ IMPORTANT: Remember that compared to online sources information found in physical media is more likely to be outdated.

Writing

You can start with a short manual like the one suggested earlier.

Once you get comfortable writing shorter pieces, move on to larger projects. Try different types of deliverables. Always think about the persona (your target audience) and adjust your language accordingly.

Write using different tools. Consider starting with the following setup:

  • Write with Markdown in Visual Studio Code
  • Publish on GitHub Pages

Regularly come back to your earlier documents and try to correct them based on what you have learned since. If you have a chance, ask someone for a review. If you don’t know anyone with a background in tech comm, you can show your work to a fellow translator. Eventually, do find someone in your target field, though. Studying together can be fun, and you’ll find lots of opportunities in the community.

  1. Sometimes less is more. You don’t need a glossary on a quick-start leaflet. ↩

Next topic: Community