For a single writer with moderate or better technical skills looking for a simple hosting solution, it's amazing. But, I've recently realized there's a problem with it that makes it ill-suited for multiple collaborators working on complicated documentation. (Or even, as I discovered, a single writer on more than one machine.)
My New Year's Resolution --- which I have so far held to --- is to write and publish every day.
Sometimes bad programming is just bad programming: people write sloppy code, people don't know how things are supposed to work, people forget that binary math is weird sometimes.
But often, bad programming is a result of bad philosophy - a fundamental misunderstanding of how meaning is made, or thought works, or how the world is structured. Sometimes the fault is a little less radical, tied to ignorance of some domain-specific facts, but often it's just plain bad philosophy.
Since I spend almost my entire day in an editor, writing, I've put a bit of effort into getting it to look the way I like. The most important things for my writing experience are:
- dark theme
- oversized display font
- syntax highlighting
- relatively narrow text (< 80 column)
- centered text with a decent margin on each side
Here is what my screen looks like when writing a blog post.
I grew up doing theatre, went to college for theatre, and taught theatre for a few years. Nearly all of my theatre experience --- as a performer, teacher, director, stagehand, designer, or even audience member --- was non-profit and the bulk was non-professional. High school, university, community, non-profit regional.
I saw a lot of shows where it didn't seem to matter who had directed it, or who had designed it. So many high school and community theatre shows are bad reproductions of the professional version of the same show. Musicals, comedies, murder mysteries... musical comedy murder mysteries. Names the audience recognizes, with poorly built sets that look pretty much the same as every other production of the show, and costumes assembled from what seems like the same pile of thrift-store refuse.
If you are doing a simple terminal script in Python, and you need to validate some user-supplied input, you can put the assignment and validation in a
try block inside a
Learning to Code is all the rage. I don't see any sign that the trend is dying down any time soon. I might as well jump on the bandwagon here and encourage my fellow tech writers to do the same.
Obviously, a lot of you already code, or are in the process of learning. I once assumed knowing at least some coding was a requirement for being a tech writer. But it seems this isn't entirely the case. Some TWs need to be able to read and write enough code to document APIs and provide code samples --- but apparently (I have learned) most tech writers aren't doing that, and you can fake your way through that if you really need to.
So, if you are among the majority of technical writers that don't code, this post is for you.
I am the master of my fate;
I am the captain of my soul.
— from Invictus, by William Ernest Henley
A strong sense of agency --- the feeling that you can, indeed, control the course of your own life --- is an essential element of success.
Unfortunately, a sense of agency can also be a source of crippling guilt and shame.
If I am not the master of my fate, then my lack of success up to this point is not my own fault. There is nothing wrong with me.
But if I am, well then --- I have some explaining to do. Why have I not lost the weight, started the business, written the book, built the app?
tl;dr - Python.
I can't even begin to count how many forum posts and deleted Stack Overflow questions there are boiling down to some version of Python vs. Ruby or, more specifically, Django vs. Rails. Google (as of right now) has NINE POINT EIGHT MILLION results for "Python vs. Ruby", which is basically insane.