For the most part, I’m quite happy with everything that I was able to accomplish last year. I’ve moved cities (for the second year in a row) and last year I changed jobs twice: in both cases, I think the current will stick for a while. And I’m working on other projects, with some impressive speed. Last year wasn’t been great for finishing things, but I guess there’s room for improvement this year.

After a fair amount of professional angst I’m finally doing pretty much exactly what I want to be doing: I’m writing a substantial/total revision of a software manual for a company developing an open source database system. I’ll leave you to figure out the details, but it’s great.

A couple years ago, I said to myself, that I wanted to be a “real technical writer,” which is to say, work with engineering teams, write documentation and tutorials for a single product or group of products, and operate on a regular release schedule. I’ve done a great deal of writing for technology companies: from project proposals and journalism, to tutorials and content for distributors, to white papers, marketing, and sales materials. Delightfully, I’ve managed to get there, and in retrospect it’s both somewhat amazing, and incredibly delightful.

A while back, I had dinner with a friend who’s been doing the same thing I do for a long time (we know each other through folk dance and singing,) and by comparing our experiences it was great to learn that my experience is quite typical, both in terms of the work I’m doing and the procedural engineering practice frustrations (e.g. “What do you mean you changed the interface without telling me?!?!”)

At work we have this thing where we send in an account of what we did during the day so that other people know what we’re working on, and so that we can keep our team on the same page. After all, when you’re all looking at computer screens all day, and in a few different time zones, it’s easy to loose track of what people are working on.

At the bottom of these emails, we’re prompted to ask “what are your blockers and impediments.” Often I say something clever like “Compiler issue with Spacetime interface or Library.” Or something to that effect. It feels like a good description of the last year.

Onward and Upward!

I have an Aeron chair at my desk at home. Confession.

I got it in April when I moved to New York City. The only piece of furniture that I had that I couldn’t move in my (now former) car was my desk chair. I found a good deal on an Aeron chair and I rationalized to myself that the cost of the chair was actually about the cost of movers. Savings right?

It also helped, that I was leaving a job where I had an Aeron chair in my office, and I knew that in the short term I would be working from home. While my old desk chair was (and is) quite nice, it’s not quite the same. Sit in an Aeron chair for a couple of two years, and it’s hard to go back. I’ve sat in other chairs since then, and it’s never quite the same.

Having said that, after a cleaning incident today, I would like to collect a few gripes about the Aeron chair for your consideration.

• The assembly right beneath the chair collects dust and dirt in a proportion that doesn’t seem quite possible. It’s clearly an artifact of the mesh, and likely a commentary on the air circulation of my apartment.

  Regardless, dusting nightmare.

• The arms scuff and scratch on desks, if the bottom of the desk isn’t completely smooth. This isn’t an actual problem: the chair still works fine and is as comfortable as ever, but it’s a annoying.

I’ve never looked at the underside of a desk before seriously. With every other chair I’ve either ordered a variant sans arms, or I’ve take then arms off as soon as possible.

The Aeron arms are low enough that they’ve never bothered me, so I thought “might as well.” But it’s still annoying.

That’s all.

I stumbled across a link somewhere along the way to a thread about the Pyramid project’s documentation planning process. It’s neat to see a community coming to what I think is the best possible technical outcome. In the course of this conversation Iain Duncan, said something that I think is worth exploring in a bit more depth. The following is directly from the list, edited only slightly:

I wonder whether some very high level tutorials on getting into Pyramid that look at the different ways you can use it would be useful? I sympathize with Chris and the other documenters because just thinking about this problem is hard: How do you introduce someone to Pyramid easily without putting blinders on them for Pyramid’s flexibility? I almost feel like there need to 2 new kinds of docs:

• easy to follow beginner docs for whatever the most common full stack scaffold is turning out to be (no idea what this is!)
• some mile high docs on how you can lay out pyramid apps differently and why you want to be able to do that. For example, I feel like hardly anyone coming to Pyramid from the new docs groks why the zca under the hood is so powerful and how you can tap into it.

Different sets of users have different needs from documentation. I think my “:Multi-Audience Documentation” post also addresses this issue.

I don’t think there are good answers and good processes that always work for documentation projects. Targeted users and audience changes a lot depending on the kind of technology at play. The needs of users (and thus the documentation) varies in response to the technical complexity and nature every project/product varies. I think, as the above example demonstrates, there’s additional complexity for software whose primary users are very technical adept (i.e. systems administrators) or even software developers themselves.

The impulse to have “beginner documentation,” and “functional documentation,” is a very common solution for many products and reflects two main user needs:

• to understand how to use something. In other words, “getting started,” documentation and tutorials.
• to understand how something works. In other words the “real” documentation.

I think it’s feasible to do both kinds of documentation within a single resource, but the struggle then revolves around making sure that the right kind of users find the content they need. That’s a problem of documentation usability and structure. But it’s not without challenges, lets think about those in the comments.

I also find myself thinking a bit about the differences between web-based documentation resources and conventional manuals in PDF or dead-tree editions. I’m not sure how to resolve these challenges, or even what the right answers are, but I think the questions are very much open.

I’m sure that most “hacker bloggers” have probably done their own “N Git Tricks,” post at this point. But git is one of those programs that has so much functionality and everyone uses it differently that there is a never ending supply of fresh posts on this topic. My use of git changes enough that I could probably write this post annaully and come up with a different 9 things. That said here’s the best list right now.

::: {.contents} :::

See Staged Differences

The git diff command shows you the difference between the last commit and the state of the current working directory. That’s really useful and you might not use it as much as you should. The --cached option shows you just the differences that you’ve staged.

This provides a way to preview your own patch, to make sure everything is in order. Crazy useful. See below for the example:

git diff --cached

Eliminate Merge Commits

In most cases, if two or more people publish commits to a shard repository, and everyone commits to remote repositories more frequently then they publish changes, when they pull, git has to make “meta commits” that make it possible to view a branching (i.e. “tree-like”) commit history in a linear form. This is good for making sure that the tool works, but it’s kind of messy, and you get histories with these artificial events in them that you really ought to remove (but no one does.) The “--rebase” option to “git pull” does this automatically and subtally rewrites your own history in such a way as to remove the need for merge commits. It’s way clever and it works. Use the following command:

git pull --rebase

There are caveats:

• You can’t have uncommitted changes in your working copy when you run this command or else it will refuse to run. Make sure everything’s committed, or use “git stash”
• Sometimes the output isn’t as clear as you’d want it to be, particularly when things don’t go right. If you don’t feel comfortable rescuing yourself in a hairy git rebase, you might want to avoid this one.
• If the merge isn’t clean, there has to be a merge commit anyway I believe.

Amend the Last Commit

This is a recent one for me..

If you commit something, but realized that you forgot to save one file, use the “--amend” switch (as below) and you get to add whatever changes you have staged to the previous commit.

git commit --amend

Note: if you amend a commit that you’ve published, you might have to do a forced update (i.e. git push -f) which can mess with the state of your collaborators and your remote repository.

Stage all of Current State

I’ve been using a versing of this function for years now as part of my download mail scheme. For some reason in my head, it’s called “readd.” In any case, the effect of this is simple:

• If a file is deleted from the working copy of the repository, remove it (git rm) from the next commit.
• Add all changes in the working copy to the next commit.

git-stage-all(){
   if [ "`git ls-files -d | wc -l`" -gt "0" ]; then; git rm --quiet `git ls-files -d`; fi
   git add .
}

So the truth of the matter is that you probably don’t want to be this blasé about commits, but it’s a great time saver if you use the rm/mv/cp commands on a git repo, and want to commit those changes, or a have a lot of small files that you want to process in one way and then snapshot the tree with git.

Editor Integration

The chances are that your text editor has some kind of git integration that makes it possible to interact with git without needing to drop into a shell.

If you use something other than emacs I leave this as an exercise for the reader. If you use emacs, get “magit,” possibly from your distribution’s repository, or from the upstream.

As an aside you probably want to add the following to your .emacs somewhere.

(setq magit-save-some-buffers nil)
(add-hook 'before-save-hook 'delete-trailing-whitespace)

Custom Git Command Aliases

In your user account’s “~/.gitconfig” file or in a per-repository “.git/config” file, it’s possible to define aliases that add bits of functionality to your git command. This is useful defining shortcuts, combinations, and for triggering arbitrary scripts. Consider the following:

[alias]
all-push  = "!git push origin master; git push secondary master"
secondary = "!git push secondary master"

Then from the command line, you can use:

git secondary
git all-push

Git Stash

“git stash” takes all of the staged changes and stores them away somewhere. This is useful if you want to break apart a number of changes into several commits, or have changes that you don’t want to get rid of (i.e. “git reset”) but also don’t want to commit. “git stash” puts staged changes onto the stash and “git stash pop” applies the changes to the current working copy. It operates as a FILO stack (e.g. “First In, Last Out”) stack in the default operation.

To be honest, I’m not a git stash power user. For me it’s just a stack that I put patches on and pull them off later. Apparently it’s possible to pop things off the stash in any order you like, and I’m sure I’m missing other subtlety.

Everyone has room for growth.

Ignore Files

You can add files and directories to a .gitignore file in the top level of your repository, and git will automatically ignore these files. One “ignore pattern” per line, and it’s possible to use shell-style globing.

This is great to avoid accidentally committing temporary files, but I also sometimes put entire sub-directories if I need to nest git repositories within git-repositories. Technically, you ought to use git’s submodule support for this, but this is easier. Here’s the list of temporary files that I use:

.DS_Store
*.swp
*~
\#*#
.#*
\#*
*fasl
*aux
*log

Host Your Own Remotes

I’ve only once accidentally said “git” when I meant “github” (or vice versa) once or twice. With github providing public git-hosting services and a great compliment of additional tooling, it’s easy forget how easy it is to host your own git repositories.

The problem is that, aside from making git dependent on one vendor, this ignores the “distributed” parts of git and all of the independence and flexibility that comes with that. If you’re familiar with how Linux/GNU/Unix works, git hosting is entirely paradigmatic.

Issue the following commands to create a repository:

mkdir -p /srv/git/repo.git
cd /srv/git/repo.git
git init --bare

Edit the .git/config file in your existing repository to include a remote block that resembles the following:

[remote "origin"]
fetch = +refs/heads/*:refs/remotes/origin/*
url = [username]@[hostname]:/srv/git/repo.git

If you already have a remote named origin, change the occurrence of the word remote in the above snippet with the name of your remote. (In multi-remote situations, I prefer to use descriptive identifier like “public” or machine’s hostnames.)

Then issue “git push origin master” on the local machine, and you’re good. You can us a command in the following form to clone this repository at any time.

git clone [username]@[hostname]:/srv/git/repo.git

Does anyone have git tricks that they’d like to share with the group?

A couple of years ago I wrote “Why Arch Linux Rocks” and “Getting the most from Arch Linux.” I’ve made a number of attempts to get more involved in the Arch project and community, but mostly I’ve been too busy working and using Arch to do actual work. Then a few weeks ago when I needed to do something minor with my system--I forget what--and I found myself thinking “this Arch thing is pretty swell, really.”

This post is a collection of the clever little things that make Arch great.

::: {.contents} :::

abs

I’m using abs as a macro for all of the things about the package build system that I enjoy.

Arch packages are easy to build for users: you download a few files read a bash script in the PKGBUILD file and run the makepkg command. Done. Arch packages are also easy to specify for developers: just specify a “build()” function and some variables int eh PKGBUILD file.

Arch may not have as many packages as Debian, but I think it’s clear that you don’t need comprehensive package coverage when making packages is trivially easy.

If you use Arch and you don’t frequent that AUR, or if you ever find yourself doing “./configure; make; make install” then you’re wasting your time or jeopardizing the stability of your server.

yaourt

The default package management tool for Arch Linux, pacman, is a completely sufficient utility. This puts pacman ahead of a number of other similar tools, but to be honest I’m not terribly wild about it. Having said that, I think that yaourt is a great thing. It provides a wrapper around all of pacman’s functionality and adds support for AUR/ABS packages in a completely idiomatic manner. The reduction in cost of installing this software is quite welcome.

It’s not “official” or supported, because it’s theoretically possible to really screw up your system with yaourt but if you’re cautious, you should be good.

yaourt -G

The main yaourt functions that I use regularly are the “-Ss” which provides a search of the AUR, and the -G option. -G just downloads the tarball with the package specification (e.g. the PKGBUILD and associated files) from the AUR and untars the archive into the current directory.

With that accomplished, it’s trivial to build and install the package, but you get to keep a record of the build files for future reference and possible tweaking. So basically, you this is the way to take away the tedium of getting packages from the AUR, while giving you more control and oversight of package installation.

rc.conf

If you’ve installed Arch, then you’re already familiar with the rc.conf file. In case you didn’t catch how it works, rc.conf is bash script that defines certain global configuration values, which in turn controls certain aspects of the boot process and process initialization.

I like that it’s centralized, that you can do all kinds of wild network configuration in the script, and I like that everything is in one place.

netcfg

In point of fact, one of primary reasons I switched to Arch Linux full time, was because of the network configuration tool, netcfg. Like the rc.conf setup, netcfg works by having a network configuration files which define a number of variables which are sourced by netcfg when imitating a network connection.

It’s all in bash, of course, and it works incredibly well. I like having network management easy to configure, and setup in a way that doesn’t require a management daemon.

Init System

Previous points have touched on this, but the “BSD-style” init system is perfect. It works quickly, and boot ups are stunningly fast: even without an SSD I got to a prompt in less than a minute, and probably not much more than 30 seconds. With an SSD: it’s even better great. The points that you should know:

• Daemon control scripts, (i.e. init scripts) are located in /etc/rc.d. There’s a pretty useful “library” of shell functions in /etc/rc.d/function and a good template file in``/etc/rc.d/skel` for use when building your own control scripts. The convention is to have clear and useful output and easy to understand scripts, and with the provided material this is pretty easy.

• In /etc/rc.conf there’s a DAEMON variable that holds an array. Place names, corresponding to the /etc/rc.d file name, of daemons in this array to start them at boot time. Daemons are started synchronously by default (i.e. order of items in this array matters and the control script must exit before running the next script.) However, if a daemon’s name is prefixed by an @ sign, the process is started in the background and the init process moves to the next item in the array without waiting.

  Start-up dependency issues are yours to address, but using order and background start-up this is trivial to implement. Background start ups lead to fast boot times.

Life has been incredibly busy and full lately and that’s been a great thing. I’ve also been focusing my time on big projects recently rather than posting updates here and updating the wiki. And then I have this day job which basically counts as a big project. While I like the opportunity to focus deeply on some subjects, I also miss the blog.

tycho is conflicted about something. Shocking.

In any case, I want to do something useful with this space more regularly. So here I am and expect me more around these parts.

I’ve been working on a total refresh of my Cyborg Institute project. I want it to be an umbrella for cool projects, nifty examples, great documentation, and smart people¹ working on cool projects. If that’s ever going to happen, I need to get something together myself. The first release will contain:

• A book-like object, that provides an introduction to the basic principals of Systems Administration for developers, “web people,” and other people who find themselves in charge of systems, without any real introduction to systems administration. (Status: 70% finished, with a couple more sections to draft and some editing left.)
• A Makefile based tasklist aggregator, inspired by org-mode but largely tool agnostic. (Status: 95% finished, with documentation editing and some final testing remaining.)
• A logging system for writers. I use it daily, and I think it’s a vast improvement over some previous attempts at script writing, and I did a pretty good job of documenting it, but it’s virtually impossible to manage/maintain. Having said that, I always wanted to rewrite it in Python (as a learning exercise,) so that might be a cool next step (Status: Finished save editing and an eventual rewrite.)
• Emacs and StumpWM config files, packaged as “starter-kits” for new users. I have good build processes for both of these. I don’t think that I need to document them fully, but I need to write some READMEs. Since there’s a lot of redistribution of others code, I need to figure out the most compatible/appropriate license. (Status: Finished except for the work of free afternoon.)

Probably, all of these Cyborg Institute projects will get released at about the same time. The blockers will be finishing/editing the book and editing everything else. I might make the release a thing, we’ll see.

Other than that, I:

• Updated /technical-writing/compilation.
• Finished the first draft of this novel. Editing will commence in June. I’ve also started planning a fiction project, for a draft to begin in the fall?
• Wrote a few paragraphs on the ISD page, but I’m starting to think that as my time becomes more limited, that the critical-futures wiki project, as such, will probably be the first thing to fall on the floor, unless someone else is really interested in making that be a thing.

Onward and Upward!

It’s been a while since I’ve written one of these “clip posts,” but there’s no time like the present to get started with that. I hope everyone out there in internet-land is having a good end of the year. I’ll try and get a retrospective/new years out in the next few days, and avoid belaboring the point here.

As I said last friday it’s my intent to focus here on shorter/quicker thoughts, and focus my free writing/project time for work on longer projects (fiction, non-fiction, perhaps some programming.) So far so good.

Recent Posts Around Here

• /posts/erstwhile-programmer
• /posts/ikiwiki-tasklist-update
• /posts/representation-and-race-futurism
• /posts/the-future-of-file-organization-and-security
• /posts/multiaudience-documentation
• /posts/knitting-in-three-dimensions
• /posts/intellectual-audience
• /posts/minimalism-versus-simplicity
• /posts/back-to-basics-tasklist-and-organization
• /posts/cyberpunk-sunset
• /posts/writing-software-for-android-and-tablets
• /posts/xen-and-kvm-failing-differently-together
• /posts/technical-writing-fiction
• /posts/whiteness-and-diversity
• /posts/longer-forms

Other Cool Things on the Internet

• Sales Cycle Theater
• Why Programmers Work at Night

A friend asked me a question (several weeks ago by publication) on a technical topic and I spent most of the next few days writing a missive on database administration strategy. That seemed like a normal response. I was delighted to find that: I liked the voice, I enjoyed writing the longer document, and there are a dozen or so other related topics that I wanted to explore. So, apparently, I’m writing a book. This is exactly what I need: more projects. Not.

But it’s a good thing: I find the writing inspiring and invigorating. I have a perspective and collection of knowledge that hasn’t been collected and presented in a single place. I like long form writing. The larger piece might also be a good contribution to my portfolio (such as it is.)

I think this kind of writing suits my attention span.

This has left me without a lot of spare time for blogging, and (as I’m prone to do every so often,) rethinking the future of my efforts on tychoish.com and as a blogger. This is boring for all of you, but I’ll give some higher level stuff here and we can follow up in comments:

• Blogging is fun, and even though I’ve not been posting regularly, I’m always writing blog posts. Sometimes I find myself writing posts in emails to friends, but I’m never really going to stop writing blog posts.

• The general explosion of blog publishing that we saw a few years ago has declined. Audience fragmentation happened, readership got entrenched. I feel like I weathered the storm pretty well and I’m really happy with the site and readers I have, but I’m also pretty confident that blogging isn’t going to be the means by which I “level up.”¹

• eBooks have finally happened. For the last decade most people have been saying that ebooks are great for reference material (given search-ability,) and for providing an introduction to a text that people will eventually buy in a paper edition. That may be true, but I think it’s changing rapidly, and with kindles and tablets and smart-phones, I think eBooks have effectively won, such as it is.

  In another ten years, perhaps, we’ll just call them books.

• I’m pretty clear that keeping a blog, and perhaps most of the writing I do in my spare time is for my own enjoyment and betterment and helps to develop a personal portfolio and account of my work. I have no (real) interest in using my writing on tychoish.com or any other side that I maintain, as a way of supporting myself to any greater or lesser extent.

I want to be in the business of writing things and working with technology and ideas and people, not the business of publishing. While the line is not always clear between “writing projects that you publish yourself online,” and “new media publisher,” I want to stay away from the later as much as possible.

So I think this means that most of my “tychoish,” writing time will go to writing this book project, and to fiction, and once my blog post backlog is fully depleted (heh,) most of my postings will either be announcements/progress-reports or a bunch of shorter more off-the-cuff notes.

Here’s hoping at least.

This post is a follow up to my earlier post on diversity and representation In short, while I think it’s great that we’re beginning to talk and write about race and representation in our fiction and field, I think we¹ need to expand our analysis of whiteness.

Whiteness in Science Fiction

I’m still working on figuring out what this means, and I’m sorry that I haven’t developed my thinking sufficiently to be more clear on this. In light of that here are a collection of my thoughts on representation:

• Whiteness is multiple and I think it’s possible (and important) to depict whiteness and white characters critically and without recapitulating normalization. At the same time, it’s important to avoid falling victim to a lot of the normalization to which uncritical representations of racial diversity often fall pray.
• The theory around race and representation must deal with issues around assimilation. More diversity is useful, but to move forward on issues of representation, the field needs to better understand the process of assimilation. I want to see stories that help us unpack assimilation.
• Whiteness is complex and a major problem with stories that “don’t do race well,” is not just that the characters aren’t explicitly of color, but that whiteness isn’t portrayed very well. This is part of the struggle of privilege, but not only does science fiction need to be better about diversity and representation of non-white characters, but we the thinking on whiteness needs to continue to evolve apace.

Diversity and Quotas

Discussions about diversity and representation in fiction often lead the under-informed to ask “So what, do you want to impose some sort of quota system? Does that mean diversity is more important than quality?”

The answer is almost always no.

I’d also like to point out that this is one of those cases where whiteness and systematic bias conspire to define “quality,” in unuseful ways. But this is another argument for another time.

The canonical answer is: there’s a great deal of amazing work written by people of color and a lot of great fiction that incorporates and addresses the experiences of people of color. This is great, and if we’ve learned anything in the last couple of years, it’s that if you look for this work it’s there. The real challenge revolves around cultivating that work so that there’s more of it, and promoting² that work so that there’s a large audience.

On Outer Alliance Podcast #8, David Levine talked about having worked as a technical writer for some 15 years and then said something to the effect of “It’s a point of great personal pride that I’ve never put a bulleted list in a piece of fiction.”

I laughed out loud. Perhaps frightening a woman walking her dog nearby.

In most ways, the kind of writing that I do for work, API references, tutorials, administration overviews, best-practice descriptions, is very different from the kinds of things I write away from work, or at least I like to think so.

The truth is that I’ve learned a bunch about writing and about communicating in general from writing documentation. While my “professional background,” doesn’t include formal technological training, I definitely “broke in” because I was familiar with technology and could write, rather than being a particularly skilled or trained writer. Any more (just 2.5 years on,) I think the inverse is more true, but that’s conjecture.

Technical writing has definitely shaped the evolution of my taste: a couple years ago, I found myself most drawn to complex tightly constructed prose in fiction. These days I mostly go for sparse clear concise prose that isn’t particularly ornamented. Perhaps it’s only really possible to tune the internal editor for one kind of style at a time.

Having said that, I will confess to feeling--and resisting--the urge to put a bulleted list or some other structured convention of software manuals in fiction.

It’s the little things, really.