Things you should know about, dear readers:

1. I published a book and released a mess under the banner of the new Cyborg Institute. These projects are:

• Systems Administration for Cyborgs

  This is a high level guide that introduces key systems administration knowledge domains and concepts. Possible subtitles include: “How to think like a systems administrator,” or “Just add man pages.”

  Read it now. Tell your friends. And please, send feedback and comments.

• Taskfile

  Rather than use org-mode, I’ve taken to using a sort of hacked together makefile that aggregates task items from other textfiles. It works surprisingly well.

• stl

  The idea behind this script is that it would provide a good way to report activity in a regular way so that I’d be able to look back over a log file and see how much I’d written (i.e. report word counts,) and also do a bunch of other straightforward reporting and logging.

  I plan to do a revision of this that’s a bit less complicated and a bit more modular, but it’s a nice proof of concept.

• stack

  I’ve been meaning to publish this for a long time, but this project contains configuration files for emacs and StumpWM, with other systems to follow.

2. I’ve made a bunch of wiki pages on Information Debt. Current pages include:

   • Books
   • Taxonomy
   • Wiki
   • Document Management
   • Hierarchy

3. I was planning on speaking at the Open Help Conference, on August 10-15th,

   2012. But then, United Airlines canceled my flight and I spent the day in Terminal C of Newark Airport and ultimately couldn’t make it for the conference. Which is a huge shame. My talk was going to be is about involving developers in documentation processes, about maintaining documentation, and about working with documentation “as code.”

   The site I made for the talk is at: http://tychoish.net/oh-2012

   And the last draft of the slides are at: http://tychoish.net/oh-2012/slides/

(I was speaking on behalf of `10gen <http://10gen.com/>`_, my employer, `MongoDB <http://docs.mongodb.org/>`_ `documentation project <http://docs.mongodb.org/>`_ that I work on by day (and sometimes night.))

There’s a folk song with the line “let the toast go free,” to which an assembled crowd of singers will often stand up and cry “free the toast!” in response.

I’ve been spending the morning going through email, reading feeds, tweaking some of the issues raised in the site improvements page, and trying to rock getting things done. In the mean time I have a few links to share.

• The Everyday Lives Of Video Game Developers
• The Price of Free
• This article, and the one before, are both open on my “things to read list. Imagine that’s what I’m doing this afternoon.
• Branchable - ikiwiki (like the wiki that powers this site) hosting service, based on publicly available tools. I kinda want to set up a branchable instance.
• Pybtex - a python/yaml drop in replacement for BibTeX, which is really cool, and I suspect that this will probably be my next citation management tool. I’ve been looking for one for a long time.
• Kindle Feeder - a tool to crawl your feeds and move them to your kindle. I’m currently sifting through my feeds and seeing what might make sense to read on the kindle. Might as well, and the automatic delivery makes a lot of sense.
• I played with ehsell for the first time today in response to this post, and I have to say that I really like it, and it’s much more intuitive and usable than I thought it’d be. I like the idea of being able to write shell functions in emacs-lisp. As an aside the post is, I think, an example of really great casual technical writing.

There are two parts to this post: first, the relationship or non-relationship between the ability to write code and technical literacy; and second, the pedagogical methods for teaching people how to program/code.

In some ways, I’ve been writing about this and related topics for quite a while: see /posts/objective-whatsis for an earlier iteration in this train of thought.

Programming and Technical Literacy

Programmers and other technical folks talk a lot about teaching young people to code as the central part of any young technical person’s education and basic computer literacy. Often this grows out of nostalgia for their own experience learning to program, but there are other factors at play.¹

In some cases, they even start or point to projects like Codecademy. Which are, in truth, really cool ideas, but I think that effectively equating the ability to write code with technical literacy is fraught:

• There are many different kinds of technical literacy and writing code is really such a small part. Sure code gives us a reasonable way to talk about things like design and architecture, but actually writing code is such a small part of developing technology.

• Writing code isn’t that important, really. In a lot of ways, code is just an implementation detail. Important as a way of describing some concepts pretty quickly, important because it’s impossible to iterate on ideas without something concrete to point to, but the implementation isn’t nearly as important as the behavior or the interface.

• For the last ~40 years, code has been the way that people design behavior and specify interfaces for software. While there are a lot of reasons why this predominantly takes the form of code, there’s not particular reason that we can’t express logic and describe interfaces using other modalities.

  There are many people who are very technically literate and productive who don’t write code, and I think that defining literacy as being able to write code, is somewhat short sighted. Also, there is another group of people who are actually programmers who don’t think of the things they do as “programming,” like people who do crazy things with spreadsheets, most librarians, among others. These non-coding programmers may shy away from programming or are mostly interested in the output of the program they write and less interested in the programming itself.

This is a huge problem. I hope that this /posts/computer-literacy-project that I’ve been planning will start to address some of these issues, but there’s even more work to do.

How to Teach People to Code

(This section of the post derives from and summaries the “How to Teach People to Program” wiki page.)

Most of the way that programming books and courses teach programming are frustrating and somewhat dire, for a few reasons:

• Most examples in programming books are dumb.
• Basic computer science/engineering knowledge is fundamental to the way that accomplished programmers think about programming but aren’t always required to teach people how to program.
• Syntax isn’t that important, but you can’t ignore it either.
• Slow reveals are really frustrating.
• The kinds of code that you write when learning to programming bear little resemblance to the actual work that programmers do.

The solutions to these problems are complex and there are many possible solutions. As a starting point:

• Separate the way you present core concepts (i.e. data structures, typing, functions, classes, etc.) from actual code examples and from actual explanations of the syntax.

  Interlink/cross reference everything, but if you give people the tools to answer their own questions they’ll learn what they actually need to know, and you can then do a better job of explaining the syntax, basic concepts, and practical examples.

• Provide longer examples that aren’t contrived.

  Examples don’t need to start from first principals, and don’t need to be entirely self contained. Programming work rarely starts from first principals (relative,) and is rarely actually self contained. It’s foolish, then to use these sorts of pedagogical tools.

Thoughts?

I kind of want to title this piece “the remains of the day,” but I’ll spare you.

This week I found myself doing something sort of different with my task list. Since I use org-mode to manage my todo list, my explanation will include a bit of “introduction to org-mode,” but I think this practice may be generally applicable regardless of the software you use.

In org-mode you can take elements of an outline--any outline--and turn it into a “todo” item, and using the agenda feature, generate views of these tasks. This is great because you can do planning and brainstorming in a manner that makes sense for you, and when you’re ready to start working, the list that you work from is organized in way that’s conducive to doing things. It’s a great system.

When you create a task, org-mode provides the ability to schedule it for a particular day or set a deadline. You can generate agenda views organized by day. This is how I work, most of the time. In the morning (on the train) I open the agenda and I see about five things per day, and I start working. The key to success, for any situation, but particularly fragmented situations like mine, is figuring out how to structure your projects and tasks such that there’s always a task that’s “small enough” no matter how short your free time is.

This works pretty well, except sometimes, you run out of free time, something takes longer than you’d like, or you reprioritize. The system of scheduling tasks breaks. Solution, at the end of your work day (or evening,) spend a moment or two going though the remains of the day’s tasks and figuring out:

• If you couldn’t get to a task was it because you simply didn’t have time, or because there was an unforeseen dependency.
• Which tasks can be rescheduled for another day (and what days would be best for this.)
• What no longer needs to be done?

At the end of the process there should be nothing left on your todo list. Now you may be tempted to engage in a little “productivity theater,” but the goal is less to “get everything done,” and more to check in with yourself more regularly, and make sure everything is on track. Also, I’m convinced being faced with scads of overdue tasks, particularly tasks that have grown stale is hardly a wining strategy either.

With the last post /posts/writing-about-technical-writing about the kind of writing I do every day for work (and work related) project, I thought it would be fun to muse, briefly about the kind of writing, I do for me.

That sounded pretentious. But it’s less pretentious, I think, than saying I write fiction for art.

Writing fiction, genre fiction at that, for me, is about talking to people directly about the way they see their worlds, about the way that we construct theories of reality, about complex systems, and maybe about all of the little thoughts and ideas that sound too foolish or too simple to justify saying plainly but are nevertheless important to say.

Fiction is a luxury, and perhaps there is why it is so crucial.

Saying, “I want to have a career as a fiction writer,” seems not very grounded in reality, and potentially even more pretentious. So here I am. I write professionally (documentation,) and I write science fiction because it’s the best way to say things that I think need saying. I’ll probably even get around to publishing fiction “professionally,” if I can, in the next couple of years, but I don’t think I’ll ever really give up the professional writing either. Writing fiction, I think, is a piece of a much larger puzzle. So there.

Two fiction writing related updates:

1. I wrote fiction Tuesday morning on the train. I’ve been working on other things for a few weeks/months, and hadn’t been able to squeeze any fiction writing in for a long time. It was good to get back to it, good to realize that I’d finished a section that had been nagging me, and could start fresh, and good to remember than I’m well into the final little stretch of this book. Just need to finish now. I’ll probably be posting more about this soon.

2. I’m really amazed by how much my “work writing” has effected and improved my fiction writing. I don’t think I was ever, exactly, a bad writer, but I’ve certainly become a better and more efficient writer, and despite the fact that fiction writing is probably the thing that has “slipped” the most for me in the last couple of years, it feels good to know that I’m still getting better at it.

I posted something new to Critical Futures today. It’s a piece about technical writing, as part of the latest installment in which has become something of a series on technical writing.

I’ve been playing, and watching this new tool, called dexy, which is really cool in its own right, but is also really cool insofar as it says: technical writing, documentation, is important and deserves great documentation tooling.

For those of you who don’t write documentation and who aren’t very involved in the mechanics of publishing lots of text to websites probably don’t find this very exciting. But it is.

In any case, in recognition of the fact that this is now a theme in my blogging and writing, I’ve created a manually generated archive for this “series” of posts. See: Posts about technical writing at Critical Futures.

There are some other modifications that I’ve made, and am making to Critical Futures. Namely: the archives page now displays a full list of all the content on the site. Hopefully this will help Google find older posts, and make them more accessible. Despite how I feel about these old posts, I think it’s good to prevent them from falling into oblivion too soon.

More changes to come soon, of course. Also real content? Hopefully!

Now: off to sing sacred harp and eat dinner with friends!

Other than shortening sentences, inserting lists, and using document structure, there are a couple of “easy edits” that I make to most documents that other send to me for review:

1. Remove all first person, both singular and plural.

2. Remove all passive sentences, typically by making the sentences more imperative.

In practice these changes are often related.

Expunge the First Person

Removing the first person is important less because it’s “more formal” to avoid the first person and more because it’s always unclear in documentation: Who are “we,” and who is “I”? Should I read “I” as “me” or as the author of the documentation? What if my experiences and environment isn’t like “ours?” While we can resolve these confusion points pretty quickly it gives users another set of information that they must track. And given that technical subjects can be difficult without confusing language, there’s no reason to make things more confusing.

People tend to think that this makes their documentation “friendlier,” “personable,” or “intimate.” People used to interacting directly with users (i.e. people doing user support) are particularly susceptible to first person problems. In support cases, that little bit of personal touch is incredibly valuable and goes a long way toward making people feel comfortable.

Those people are wrong. Don’t do it. Speak simply. Write about the product and the processes you’re documenting, not yourself. Convey facts, not opinions. Provide context, not perspective. If you’re writing the official documentation for a product, your perspective is obvious to readers; if you’re not writing the official documentation, that’s also apparent and probably not your job to disclaim.

Use Good Verbs

Passive sentences and weak verbs are a huge problem. Huge. People with science and engineering back rounds seem to prefer passive sentences because they think that passive sentences convey objectivity, and that this objectivity is desirable.

Passive sentences do convey a sense of objectivity, and there are some cases where there’s no way to avoid describing a property of a thing except passively. That doesn’t make the passive voice generally acceptable. Related to the reason above, passive voice tends to provide a level of “syntatic indirection,” and means that complicated sentences become unnecessarily difficult to comprehend.

In documentation, unlike some other forms, it’s possible (and desirable!) to use imperative verbs, which provides some relief. One of the main projects of documentation is to inculcate “best practices” (i.e. values and conventions,) in users. Imperative verbs are great for this purpose.

In short: Do it!

My Decision

Throughout this spring I’ve been eagerly waiting for the announcement and arrival of the new X-series laptops from Lenovo. I’ve been incredibly happy with every Thinkpad I’ve ever had, and while my existing laptop--a very swell T510--has been great, it was time:

• I needed a system with a bit more power. The power of my existing system was being to frustrate me. Things took too long to compile, I was having some annoying networking processing issues, and to make matters worse…

• The thing was huge. I think 15 inch laptops are a great size for doing actual work, and I’m not getting rid of this one, but it’s not the kind of thing I want to lug on my back. Which I was doing a lot.

• I needed more redundancy. Most of my work in the world--writing, hacking, communicating--happens with a computer. While my data is backed up (never well enough, of course, but it’s there,) I worry more about the case where I’m stranded for a period of time without a working system.

  This facilitates not only piece of mind, but also makes it possible to do things like: upgrade the T510 from 32 to 64 bits. (Don’t ask.)

• In the long run, the older laptop might need to go to R. who’s personal system bit the dust a few months ago.

What Happened

But, when the new x230s came out and I found myself unimpressed. The revision got a different keyboard and I adore the old keyboard. To make matters worse the screen on the new model wasn’t any better than the one on the old: the pixel density is somewhat crappy.

In light of this, and mostly for the older keyboard, I decided to buy the older model. In short: it’s great.

I bought the RAM and hard drive aftermarket, and replaced them before booting the first time. Having 16 gigs of RAM is pretty much amazing, and I’m sold on the notion that SSDs are now a must for most common personal computing work.

Incidentally I discovered that this computer is about the same weight as the 13 inch Macbook Air (and I have the larger battery), for those of you keeping score at home. And way beefier. Thicker obviously, but still…

Point by Point

Pros:

• The keyboard is the same great Thinkpad keyboard we’ve always had. I’m sure eventually I’ll give in and learn to enjoy the new keyboard, but for now, I’m going to stick with the old.
• It’s way fast. Because, the speed of my old computer defined “the speed of computers,” in my mind, it was kind of nifty to learn that computers had actually gotten faster.
• It’s way small. Turns out, if I’m lugging a sub-3 pound laptop around, I can totally use my awesome shoulder bag. I also don’t feel like my wrist is going to give out if I need to walk 30 feet holding the laptop in one hand.

Cons:

• The screen could be so much better than it is, and there’s really no excuse. It’s not enough of a deal breaker for me, but…
• That’s really it. I think 12 inch wide screen laptops don’t have quite enough wrist-rest area on them, but that’s really an unavoidable problem: if you have a wide secreen (and thus a full keyboard,) the wrist area is short and narrow. If you have a more square screen and a squished keyboard, then you have enough wrist area. One adjusts.