Editor-in-Chief of Current Affairs book recommendations
A reading list for the left
Nathan J. Robinson’s 2019 book, Why You Should be a Socialist, ends with a left media diet or in other words, a leftist reading list. These recommendations cover a large set of categories and I felt it would be best to share these texts. Some of the issues I faced in putting together this list was creating the categories in which to organize the text. Some texts could fit into multiple categories while others texts deserve a category on their own. For simplicity sake, this list summarizes his recommendations in hopes of providing discourse around leftist thought.
Leftist book publisher:
Three ways to improve your user experience.
How are users finding your documentation?
I believe the most overlooked concept of technical writing is discoverability. It does not matter how accurate your documents are if your users cant discover them. I believe discoverability covers three important cross-sectional fields that technical writers should pay attention to:
- Search engine optimization
- Table of contents
- Relevant information
Search engine optimization:
Your search engine optimization (SEO) should allow your users to quickly google your documents. When constructing your documents think about different ways your users will discover this document. This includes titles, key words, metadata, links to other pages, and naming conventions in the URL. SEO matters to you…
Tired of the same old same old?
Some alternative learning sources
In this blog post, I want to highlight the not-so-mainstream approaches to learning about technical writing. I have found these resources to be helpful for people who want to learn more about documentation or want to improve their skills as a writer. I think its important for all writers to constantly improve their skills and learn as much as possible.
Open Oregon
The writers of this project have put together a great introduction to technical writing. It reads like a text book with an emphasis on audience, document design, and the research process. The writers used the Open Press publishing service which…
Why Postman should be included in your writing workflow
One of the most useful features for Postman is its documentation feature.
What is Postman?
Postman is a software development toll that enables people to test calls to APIs. Postman is able to do this when the user enters data, that data is sent to the specified web server address, and in most cases the information is returned to the user.
What is an API?
An API is an acronym for application programming interface, which allows interaction between multiple software intermediaries.
For example, if you wanted to see all pull requests on a repo in GitHub, you could go into the GitHub’s web interface and click each repo and select pull requests…
A new solution to documentation
Developer portal that places priority on documentation
In this article I will be taking a closer look at Spotify’s Backstage plugin TechDocs. Backstage is a centralized service catalog. One of Backstage’s plugins, called TechDocs, offers a much needed documentation solution.
TechDocs lets the developers write in markdown and that documentation lives with the code, embracing the docs-like-code philosophy and allowing for a centralized place for the docs to be read. The Backstage documentation suggest that more syntaxes will be supported like rst and AsciiDocs.
TechDocs Core Plugin is built with MkDocs, which is a light-weight static site generator that creates a “wrapper around multiple MkDocs plugins and…
Most asked questions for writers in the software industry
Questions on technical writing
Many people who are interested in technical writing frequently ask me a lot of different questions, I have compiled a list of questions and answers to help address some of the most frequently asked questions.
What tools do you use for technical writing
I am a firm believer that a writer can adapt to any tool as long as it doesn’t hinder them from writing and publishing. That being said, the software industry requires tools to be adaptive to the content that you’re writing for.
Oxygen — Oxygen XML is one of the best tools for structured content. It allows…
Technical writing’s newest trend
LwDITA and the future of documentation
According to oasis-open.org, “Lightweight DITA is a standards-based alternative for situations in which DITA 1.3 would be too complex or for communities that do not use XML as an authoring platform” meaning: Lightweight DITA (LwDita) is an alternative solution for a standardized markup language that is easy to learn and easy to use. It seems like a vial be compromise between DITA XML and markdown.
The goal of LwDITA is:
- Provide a simpler DITA experience
- Provide mappings between XML, HTML5, and Markdown that enable individuals to:
- Author content in the format of their choice
- Easily exchange and publish content whose…
Good code means good comments
The importance of code comments
Code comments act as metadata for code. Code comments are used to instruct or clarify portions of your code. Creating code comments will help the consumers of your code understand, use, and modify your code in the future. Code comments are supplemental and developers shouldn’t rely on code comments to excuse poorly designed and written code.
In this article, I will explain the importance of code comments. I refrain from giving specific examples of code comments as most examples come across as hyperbolic. …
Find out the benefits from treating docs like code
How to standout in the technical communication industry.
Docs Like Code, also known as Docs as Code, has been a recent trend in the technical communication community. Anne Gentle has even written a book by the same title, “Docs Like Code”. More technical writing jobs are being created in the software industry and having this skill set will make you a better technical writer.
Treating documentation like code means that the documentation should be stored in some sort of version control system, like Git. The documentation should go through a review. The documentation tool-chain should be automated. …
Some of these results may shock you
What you need to know before looking for a new job
According to the U.S. Bureau of Labor Statistics, there were 55,700 technical writers in 2018. BLS projected an 8% growth which means, at the time of this writing there are around 65,000 technical writers in 2020.
Technical writers research and create instruction manuals, how-to guides, and other supporting technical information for a variety of fields.
Because of the fast growth for a relatively small field I was interested in seeing what the actual job outlook looked for someone in the current economy. To my surprise, there was a lot.
A quick LinkedIn search for technical writing for the United States…
