Technical Writing in A Modern World

   What is a technical writer? If you prick one will they bleed blood? Or will it be facts, figures and diagrams?

Sarah Maddox writes in her blog  about a book by Andrew Etter(a self published writer):  Modern Technical Writing: An Introduction to Software Documentation

In his book, Andrew goes over the key aspects of what he believes about  being a technical writer in today’s world:

  • Learn: Know what you’re talking about and why your audience should care.
  • Write in Lightweight Markup: Markup languages are a system for annotating a document that makes it clear that it’s not text. (Example the link above is HTML Hypertext Markup Language). Lightweight Markup can get you from a “Pleasant writing experience to a useful website”
  • Create static websites: A web page with fixed content.
  • Treat docs as code

Ms.Maddox then writes about the process for Mr.Etter to get his book out , his price range and the troubles he had while publishing.

Mr.Etter then began to speak about the value of a technical Writer. The things that make the job unique. The points he  brought to the table were :

  • Consistency- Regarding tooling. Mr. Etter claims that without tech writers engineering teams would have to pick their own tools “which would result in chaos”. As a budding Computer Engineer I can appreciate that.
  • Accountability – The documentation needs to be good or else some gets a pink slip.
  • Creation and C : The writers have a community that can review and take care of each other’s content.
  • Culture- Having people who really know what they’re doing, allows you to know what your document should look like.
  • They can help an organization save time. And time is money.

Finally  goes over the old and the new ways of producing documentation, which can be found in Mr.Etter’s: Modern Technical Writing: An Introduction to Software Documentation

A good 45 minute read that should illuminate,destroy common myths, clear misconceptions about Technical Writing today.

-Hakeem Buchanan

Blog found at:


Writing Memos

The topic that has been most useful to me this semester, and will likely be the most useful to me for the rest of my life were the topics requiring us to write memos about different circumstances or proposals. Before this class I only had a vague idea about what memos even were, and never had to read much less write one. I’ve also never done any sort of real technical research before this class, so all of the assignments having us look up and present information in a clear and meaningful way has given me a foundation of how to do this well in the real world.

Outside of my civil classes, no class has been as useful as this class in preparing me for working in a professional environment. I learned how to work with contractors and my superiors while on my co-ops, but they never showed me how to communicate outside of talking. Without this class I feel I’d be struggling a bit when I get my first real job, so I’m glad I had to take it.

Connor Butcka

Content isn’t really the only important thing

Even though it is the content in a document which transmits the message, having a good design and a well structured document helps a lot to transmit the message.

The design of the document won’t be the same for the different reader profiles and if there is too much text without some kind of visual aid on the page or images, the reader can get bored or distracted and fail to completely understand the message.

Comparison between a bad and a good design

Comparison between a bad and a good design

Before taking this class I knew that information must first get to the audience by being appeal where it is placed and how it is placed. For example, a webpage that has a bad visual design won’t be as effective a good-looking webpage even if both have the same content.

I believe that documents should follow the same rule, it has to be attractive at first sight in order to incite the reader to read it entirely. I think this goes from the text-font to the layout of the text and even the color and size of the text influences the document.

I just navigated the New York Times website and opened the starred article.

Image Gallery - The New York Times

The article starts with a text column on the left and an image gallery on the right.

Monica Pagan, left, 26, and Kathryn Duque, center, 25, both from Queens, had Champagne on the Arthur Ross Terrace. Credit Ashley Gilbertson for The New York Times

After another paragraph, the article presents an embedded tweeted image and the pattern repeats itself, presenting another image after a couple of paragraphs.

What does $375 get you at AMNH sleepover? Dessert, among other things

This article without all of those images and tweets wouldn’t be that appealing to the sight as it is now. Furthermore, the webpage has a simple style which doesn’t overload the page with colors, or advertisements, which lets you focus on what is important.