Tags: documentation

Manual Work Is a Bug: Always Be Automating

Let me tell you about two systems administrators I know. Both were overloaded, busy IT engineers. Both had many repetitive tasks to do. Both wanted to automate these tasks. After observing these two people for a year, I noticed that one made a lot of progress, while the other one didn't. It wasn't...
Read 0 Comments

RTFM? How to Write a Manual Worth Reading

There's common wisdom in the open source world: Everybody knows that the documentation is awful, that nobody wants to write it, and that this is just the way things are. But the truth is that there are lots of people who want to write the docs. We just make it too hard for them to participate. So...
Read 0 Comments

typewriter-801921_1920.jpg

documentation
Writing in English for an international audience takes work; here are some handy tips to remember.

5 Tips to Improve Technical Writing for an International Audience

Writing in English for an international audience does not necessarily put native English speakers in a better position. On the contrary, they tend to forget that the document's language might not be the first language of the audience. Let's have a look at the following simple sentence as an example...
Read 2 Comments

Secrets of Writing Good Documentation

Taylor Barnett, a Community Engineer at Keen IO, says practice and constant iteration are key to writing good documentation.  At the upcoming API Strategy & Practice Conference 2017, Oct. 31 -Nov. 2 in Portland, OR, Barnett will explain the different types of docs and describe some best...
Read 0 Comments

Top 5 Linux Pain Points in 2017

As I discussed in my 2016 Open Source Yearbook article on troubleshooting tips for the 5 most common Linux issues, Linux installs and operates as expected for most users, but some inevitably run into problems. How have things changed over the past year in this regard? Once again, I posted the...
Read 0 Comments

os-tools.jpg

open source guides
The Tools for Managing Open Source Programs guide provides an exhaustive collection of categorized tools that any open source program can benefit from.

Tools for Managing Open Source Programs: A Free Guide

Is your organization looking to build out an open source program? If so, you’re not alone, but not every organization has a holistic sense of the available tools that can help create a healthy program. A simple charter document and a few spreadsheets for tracking projects won’t cut it anymore in...
Read 1 Comments

Tools and Practices for Documenting Microservices

I will assume you are at least familiar with the concept of microservices — loosely coupled services that provide discrete solutions to business use cases that you can combine to solve current needs and demand. The architectural pattern has gained popularity over the past years, and although not...
Read 0 Comments

Modular Documentation: How to Make Both Writers and Users Happy

Modular documentation is not a new concept. Writing documentation in modules that can be combined and reused has been around, in various incarnations, for many years, and it has many proponents as well as detractors. This article introduces a lightweight approach to documentation modularity. The...
Read 0 Comments

The Ten Essentials for Good API Documentation

API documentation is the number one reference for anyone implementing your API, and it can profoundly influence the developer experience. Because it describes what services an application programming interface offers and how to use those services, your documentation will inevitably create an...
Read 0 Comments

How to Write Documentation That's Actually Useful

Now more than ever we need well-documented code. Here are four ways to make sure your applications make sense to humans as well as to computers. Programmers love to write code, but they hate to write documentation. Developers always want to read documentation when they inherit a project, but...
Read 0 Comments

Pages

Click Here!