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:
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:
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…
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.
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…
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…
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…
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…
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:
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. …
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. …
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…