Documentation Maximalism

You may hear people, particularly people who don't like to write documentation, something like: Users need minimalist documentation that only answers their questions, and there's no point in overwhelming users with bloated, maximalist documentation that they'll never read. Which sounds great, but doesn't reflect reality or best practice. Consider the following: Documentation is as much for the producers of the software as it is for the users. Having extensive documentation contributes too, and reflects a sane design process.…

Keep reading

Information Debts

Like technical debt, information debt is a huge problem for all kinds of organizations, and one that all technical writers need to be aware and able to combat directly. Let's backup a little... Information debt is what happens when there aren't proper systems, tools, and processes in place to maintain and create high quality information resources. A number of unfortunate and expensive things result: People spend time recreating documents, pages, and research that already exists.…

Keep reading

Novel Automation

This post is a follow up to the interlude in the /posts/programming-tutorials post, which part of an ongoing series of posts on programmer training and related issues in technological literacy and education. In short, creating novel automations is hard. The process would have to look something like: Realize that you have an unfulfilled software need. Decide what the proper solution to that need is. Make sure the solution is sufficiently flexible to be able to support all required complexity.…

Keep reading

Programming Tutorials

This post is a follow up to my :doc`/posts/coding-pedagogy` post. This "series," addresses how people learn how to program, the state of the technical materials that support this education process, and the role of programming in technology development. I've wanted to learn how to program for a while and I've been perpetually frustrated by pretty much every lesson or document I've ever encountered in this search. This is hyperbolic, but it's pretty close to the truth.…

Keep reading

Project Orientation

(or my latest attempt to do things in a more "project oriented way.") This post is about recent projects, projects that I'm working on, and how my work has changed in recent months. A couple of weeks ago, I finally posted all of the content that I've been working on for the new, revived Cyborg Institute. While the book on systems administration itself had been mostly done for a while, I'd delayed for two reasons:…

Keep reading

imenu for Markdown

For a while, I've been envious of some of the project and file navigation features in emacs for browsing bigger projects/programs, things like imenu and tags have always seems awesome but given that I spend most of time editing restructured text and markdown files (I'm a technical writer), these tools have been distant and not a part of my day to day work. It's not that it would be impossible to write interfaces for imenu or etags, for the formats I use regularly, but more that I've never gotten around to it until now.…

Keep reading

Practical Branch Layout

I've recently gone from being someone who uses git entirely "on my own," to being someone who uses git with a lot of other people at once. I've also had to introduce git to the uninitiated a few times. These have both been notable challenges. Git is hard, particularly in these contexts: not only are there many concepts to learn, but there's no single proscribed workflow and a multitude of workflow possibilities.…

Keep reading