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.

In no particular order:

Org Mode Guilt and a Lisp Function

I have some guilt about having mostly forsaken org-mode,¹ in particular because I was watching Sacha Chua’s chat with John Wiegley, and I think both are such nifty hackers, and have done so many things that are pretty darn nifty.

I liked what I heard about johnw’s org mode setup so much that I might give it a try again. But in the mean time, I wanted to make my “recompile my tasklist function” to be a bit more clean. The result is follows:

(defun tychoish-todo-compile ()
   (interactive)
   (if (get-buffer "*todo-compile*")
       (progn
          (switch-to-buffer-other-window (get-buffer "*todo-compile*"))
          (recompile))
       (progn
          (compile "make -j -k -C ~/wiki")
          (switch-to-buffer-other-window "*compilation*")
          (rename-buffer "*todo-compile*")))
       (revbufs))

Notables:

• This is the first time I’ve used progn which is somewhat embarrassing, but it’s a great thing to have in the toolkit now. Link: progn
• I hadn’t realized until now that there wasn’t an else-if form in emacs lisp. Weird, but it makes sense.
• Compilation Mode is pretty much my current favorite thing in emacs.
• revbufs is this amazing thing that reverts buffers if there aren’t local modifications, and also reports to you if a buffer has changed outside of emacs and there are local modifications. So basically “does everything you want without destroying anything and then tells you what you need to do manually.” Smart. Simple. Perfect.

I might need to “macro-ize” this, as I have a lot of little compile processes for which I’d like to be able to trigger/maintain unique compile buffers. That’s a project for another day.

Emacs Thoughts

I’m even thinking about putting together a post about how, although I’m a diehard emacs user, and I’ve spent a fair bit of time learning how to do really great things with emacs, there are a lot of vim-ish things in my workflow:

• I read email with mutt and I’ve tried to get into GNUS, and I try it again every now and then, but I always find it so unbelievably gnarly. At least the transition. Same with Notmuch, which I like a lot more (in theory,) but I find the fact that Notmuch and mutt have this fundamental misunderstanding about what constitutes a “read” email, to be tragic.

• I use a crazy ikiwiki + deft + makefile setup for task tracking. As (obliquely) referenced above.

  I might give org another shot, and I’ve been looking at task warrior, but the sad truth is that what I have works incredibly well for in most cases, and switching is hard.

• I tend jump to a shell window to do version control and other things, even though I’m familiar with magit and dired, my use of these tools is somewhat spotty.

After doing the first pass of editing on my technical book, “Systems Administration for Cyborgs” on a screen and feeling utterly buried by it, (See: /posts/the-editing-hole,) and I’m considering different approaches for the next book. Specifically, for this novel I have, I’m thinking about getting the novel printed somehow and then editing it “analog style.”

I’d love to hear feedback from anyone who has done this, particularly recently. Particularly from people who are very digitally savy. Here’s my pro/con list:

Pros:

• It might be nice to have a different “editing context,” to help me keep focus on the project without the distractions of the internet and current writing projects.
• Having marked-up pages gives me an actual marker of progress, rather than a list of commits or diffs.
• It might be nice to get some practice writing longhand again. It’s embarrassing when someone hands me a pen and I’ve basically forgotten how to use it.
• It gives me a start to a collection of paper ephemera that I can burden some archivist with at some point.

Cons:

• Context switching, from a computer, to paper, to a tablet, or whatever is annoying and eats time/focus.
• Paper would force a more linear editing process, which may get me to focus on the story and characters more closely at the possible expense of seeing “broken sentences,” and other things that may be distracting to the next readers/editors/etc.
• If I edit on paper, I have to go through and apply those changes to the actual text. Which adds a step, and probably a number of additional weeks to the editing process.
• I’m awful writing things out long hand and I pretty much haven’t written anything long hand in 4 or 5 years.

Reflections

There’s also another little thorny problem: I’m not sure what the future of this book is: The prologue stands alone, and I want to try shopping it around. If I can get that published as a short that might be the hook to getting the rest of the book published.

Initially my plan was to have a friend read it as a podcast, and attempt to publish the prologue as a short, and then try and for-real publish the next book. The podcasting idea, while nice, wouldn’t work out as originally planned (long story.) Besides, it really depended on having someone else to the reading (I have neither the time, technical skills, nor the real ability to do the reading.) Which leaves me without a plan, and the following thoughts about the publication of this text:

• I feel like my writing career¹ is in good (enough) shape that my identity as a writer depends on publishing this novel in a particular way.
• On the other hand, getting the novel (or parts of it published) would be a great thing, and validates all this time/energy/interest that I have in writing science fiction.
• I’m not opposed to self publishing, except that it means more work for me for what is probably less impact (i.e. readers.)
• It took me embarrassingly long to write this novel. And knowing how much better my writing has gotten in the last three or four years, means that I’m pretty worried that this is really a cold pile of shit. I recognize that this is probably more reason to get the novel out to first readers, but I also feel like I should do them the favor of at least a little editing.

Printing in the Digital Age

As an aside, this has given me some time to do research on getting things printed, which I’d like to record here and share with you:

(Given a 325-350 page manuscript)

• I don’t own a printer, and have no particular interest in owning one, but a good color laser (in the 300-400 USD) or a good black and white (200-300 USD) becomes much more economical if analog editing becomes a thing.

  The downside of printing things yourself is that you still need some way to bind things. And there are maintenance and supply costs not factored into the above.

• The price to get printing/binding done at Staples is in the 35-40 range. Chances are that these copies are likely to be the highest quality, quickest turn around, and the web interface--though annoying--is probably the most straight forward.

• You can use Lulu.com to order prints. The same book costs 15 bucks. It’s also spiral bound (which seems preferable to perfect binding for writing.) I’m not sure what “lulu standard” paper is like quality wise, but I suspect it will be ok. If you’re ok with a fussy online interface, a weird approach to covers (no really, I’d just like transparent covers,) and turn around time, the price seems unbeatable.

Also, Lulu’s cover making interface makes it really hard to get a plain cover that doesn’t look like a joke.

I did some hunting around for local copy shops (I swear it seems like I pass several on my walk to work,) but had difficult finding a shop who would be able to do a very small order, and has the digital setup to accept a PDF for printing via email or a web site.

The success or failure of the collar of a sweater determines the success or failure of an entire sweater. This post provides an overview of my basic: “how to knit a collar” system that usually works for me and some thoughts on why collars are so important.

The hard part of collars is that on the whole, collar shaping accounts for five or ten percent of the knitting, but weeks or months worth of work hangs in the balance. The collar affects both the overall style of the sweater and has a great impact on how you will feel about the sweater when you wear it. A collar that doesn’t hang right, or is too narrow or too wide is the worst: the right collar can also make a sweater that is otherwise too light feel just warm enough and more importantly the sweater that’s too heavy not feel oppressively warm.

So how do you knit a collar?

Easy.

The fine print: These instructions assume that you’re knitting the sweater in the round.</small>

For a basic, round, crew neck…

Figure out how long your sweater will be from the top of the shoulder seam to the bottom hem. Typically this is the length measurement in the pattern and you can measure it easily yourself.

Figure out how many stitches around your collar opening needs to be at the very end, but the width of the hole at the top seam. Because you’re shaping the collar, the number of stitches on the collar as you knit it will be slightly higher because of the angles/sloped edges. Typically this is 13-16 inches for most people.

Elizabeth Zimmerman would figure 1/3rd of K, which is a good starting point, but if your sweater has too much ease or if your making a sweater in excess of 40 inches (which isn’t too big,) I think you’ll end up with neck openings that are a little too wide.

Before you start, compute the following values:

• Half of the total collar width. This is the total number of stitches that you need to set aside or decrease by the time you get to the shoulder seam on the front and the back.
• About half of this number or a quarter of the total (or a bit less, round down here, if need be) to set aside at the base of the neck.
• The total number of stitches minus the actual number of stitches set aside at the bottom of the neck, if your math is fuzzy. This is the number of stitches that you have to decrease on either side of the neck. This number must be even.
• The distance between the bottom of the neck and the top of the shoulder. This is almost always within a half an inch of 3 inches. Also record the number of rows.

With these numbers in hand, do the following.

Three (3) inches before this length, begin the collar shaping. (Change depth as needed.)

Set aside stitches at the bottom of the neck.

Decrease on either side of the neck opening (possibly using a steek,) every row until you have decreased half of the number of stitches that you need to decrease. Typically this should take about an inch and a half of knitting, or half of the total collar depth to accomplish.

After you’ve knitted half of the total collar depth, figure out how many stitches you’ve decreased at this point. Set this number of stitches aside in the middle of the back of the sweater.

Meanwhile: Create a new steak or begin decreasing at the back of the neck at the same rate as you decrease at the front.

Now decrease at half the rate (e.g. every other row) for the remainder of the depth of your collar opening. Bind off. You’ve made a sweater.

If you time it right, and your stitches are not too short and wide, this basically works out to: set aside stitches at the front, decrease every row for an inch and a half, set aside stitches at the back, decrease every other row for an inch and a half. Bind off for shoulders.

Variants:

• Knit more on the front so that the shoulder seam is actually at the top of the back, and the front of the sweater extends over the top of the shoulder.

• Use shoulder saddles or straps to increase the depth of the neck. This is a perpendicular strip of knitting that starts at the side of the neck and extends across the shoulders and forms the top part of the sleeve.

  In this case, subtract half of the width of the saddle/strap from the depth of the collar opening, and twice the width from the opening. Adjust accordingly: typically the best thing to do is figure out how much additional depth you need to decrease, figure out how many rows that will be, and plan to decrease on every row and set aside the remainder. Depending on the depth you may need to “fill in” or shape some of the depth on the back of the neck.

• If your shoulders slope downward, consider short rows across one or both of the sides, to make the top of the sweater a bit more conical.

• I often make Henly-style sweaters by setting aside a single stitch (and knitting a steek) 3-5 inches bellow the bottom of the collar. This keeps sweaters from becoming too warm.

I’ve had a nice quiet weekend, the first such weekend in quite a while. It’s nice to be able to relax, work on projects without deadlines, and avoid all of the editing that I ought to be doing.

Some notable accomplishments, current projects, and other events in the last few weeks:

• If you ever visit tychoish.com in your web browser (as opposed to by way of its aggregation,) you’ll note that the design has changed somewhat.

  This is the design that I’ve been using for my personal wiki for months, and so I’m quite used to it, but feedback is welcome.

  The design change has inspired a bit of introspection, hence this post, and perhaps some of the posts that will follow. Please bear with me.

• Months ago a friend of mine said “some of us might like to know how you’re doing every now and then, and your blog is just stuff about obscure technology.”

  Guilty as charged. Recently, I’ve been much more interested in using this blog as a scratch space for projects that I don’t have quite enough time to pursue in appropriate depth.

  Having said that, I think (or hoped,) that I’ve calmed down a bit in recent months and years: My career/professional identity seems a bit more stable. I’m doing a better job at focusing big projects, which means some shorter posts and more personal posts may be in order.

• I got a new computer last week. I’m working on a post that addresses this in a bit more depth. In short it’s great. So my largely unnecessary justification is:

  • A smaller machine, which is better on my back when I am walking around.
  • Beefier system, which means I can compile things quicker (and I’ve been doing more of this recently.)

• The ability to dedicate the older system to some stay at home things: having a working desk at home, playing music, running some buildbot stuff, and the like.

I’ve realized that even though there are little things that I might like to change about how my computer works, and things that I’d like to setup and get working for the most part, things just work. And that’s really great.

• There’s a host of stuff that I’m working on that probably isn’t apparent to the internet:

  • My day job. I’m doing awesome documentation things for a neat New York City database software company/open source project that you’ve probably heard of (if you’re into this kind of thing.) It’s rewarding, interesting, and it means I can spend all most of my time day making things.
  • I’ve been working on submitting documentation patches to a couple of open source projects: buildbot and MediaGoblin. I need to do more of this work.
  • The editing pile. Currently on tap: a mess of blog posts, the prologue of my most recently drafted novel, and some of the last little pieces of the Cyborg Institute launch. Speaking of which that should happen in the next week or so.

  Next up? More of the novel and suggestions from frist readers of the systems administration book (see next item.)

• Never to be deterred, I’m hard at work on the outline for another novel. The plan is to have something I can start drafting in earnest by the end of the summer. I feel pretty good about the project, although as I was working on an outline last night, I changed the last third of the book. Oops.

• The systems administration book. Available via git today, With general release following shortly. All feedback as well as pull or merge requests with comments and suggestions are all welcome. See the following for git repositories

  • administration on git.cyborginstitute.net
  • administration on github.com

  (Both are identical.)

  The cyborg institute listserv would be a good place for bug/issue tracking at least for now.

• On the topic of editing, I’ve recently discovered the one clause per-line formatting style.

I’ve long attempted to keep lines short to promote cleaner diffs, but in truth, if you end up reflowing paragraphs, the resulting diffs are basically useless. I’ve encountered one-sentence-per-line tactics, which seems like a good idea, except that sentences often exceed 80 characters.

I’m not yet decided on the subject, especially for writing longer sections of text, but it does make editing easier.

Onward and Upward!

In the course of writing a computer program, engineers typically face the same kinds problems again and again. As a result programmers have developed a way of thinking about different kinds of solutions and situations as “patterns,” which provide generalized ways of talking about common problems and strategies.

> See: Portland Pattern Repository for an > example catalog of programming patterns.

When I opened the editor to write this post, I wanted to write something to connect this idea of a “pattern” with a knitting pattern, which I think is (or could be) a very related concept.

Rather thank think about knitting designs as these static instructions for constructing a single kind of garment, I think it might be cool to think of knitting patterns in the sense that programmers use the word: as a set of generalized responses to various states and situations.

This isn’t revolutionary. If you’ve been knitting seriously for more than a couple of years, you probably already think about knitting in this way. At the same time, knitting publishers organize information in other ways: knitting “content” is either design and object centric (how to knit a “thing,”) or it’s technique centric (how to make a specific kind of “stitch” or “how to execute a specific kind of operation.”)

Patterns are good because they are guides to become more creative and more resourceful knitters. Patterns help us understand how to effectively use resources, to execute the objects that we want to without dithering, and how to fix mistakes in our knitting when we make them. Focusing on knitting “patterns,” is not only important because knitters will find them useful, but because it will advance the state of the craft.

Patterns also help resolve an ongoing “problem” in the knitting world: an online, free culture repository of information about knitting.

In the decade or so, I’ve watched a number of knitters attempt to create online information resources that serve as a free culture repository for knitting. Nothing has been particularly successful, and there’s not a lot of “knitting free culture” out there.

While the lack of knitting free culture is due to a large number of factors, the fact that knitting content has always centered on “objects” and “techniques” is almost certainly a factor:

• objects are difficult to design, represent professional designer’s only real way of generating a reputation and income, and it’s difficult to divide the work of writing instructions for creating objects.
• there are a few (3-5) really, really good knitting techniques compendiums, and while new techniques emerge every now and then the books from 1938 (Mary Thomas’) are as good as any of the more recent examples.

Patterns in this sense might be the best way to build an online knitting resource. Rather than store indexes upon indexes of cast on methods, full patterns for garments, and stitch patterns, we could create an index of knitting patterns, generated and indexed by situation and purpose. Example patterns might include:

• Heels for Light Weight socks.
• Heels for thick socks.
• Crew neck collars.
• How to knit sweaters in the round when you don’t want to steek.
• How to secure a steek if the yarn isn’t wool.
• Knitting socks for high arches.

And so forth…

I’m going to use my (admittedly sporadic) knitting blogging to begin capturing some of these knitting patterns. Then, if there’s interest, we can convert these into a more robust form.

Anyone interested?