I’ve been writing a series of terribly self indulgent posts about thinking about creative projects as work and about the habit and rhythm that I’ve been using to get work done, even under adverse circumstances. As exciting as the increased blogging and progress on fiction projects is, I’m just as excited about figuring out how to squeeze in knitting and reading time into my days.

And not to overshadow the importance of figuring out how to make the best of my time, but the other major factor in my return to knitting is that I finally finished the plain sweater that I’d been working on for 7 months (or so) and got to cast on a sweater with a two-color pattern, in a nifty yarn, and a pattern that’s strongly reminiscent of my favorite sweater.

I’ve discovered that while plain knitting is soothing, in many ways, it’s not particularly fulfilling or engaging. I’ve knit--at time of writing--about 9 inches of the body section. This means, I’m about half way to the under arm of the sweater. I don’t know if this will linger, but at the moment, I’m so looking forward to this sweater, that I think I might make a series of sweaters based on this, or similar patterns.

I suspect I’ll be blogging about this project for a little while, but here are the basics: the pattern is Swedish/Norwegian in styling. The yarn are black and a hand-dyed, from a dyer in Wisconsin that I had made specifically for this project. The background color is called “tree bark,” and it’s very autumnal and the foreground color is black, so it has a sort of stained glass/water color look to it. The contrast isn’t as strong as I had hoped, but the base yarn is similar to the “Shaffer Anne” sock yarn (if that’s meaningful to any of you,) and it feels lovely.

Good enough for me!

See “Why The World Is Ready For Dexy” and “Dexy and Literate Documentation” as well as the technical writing section section of the tychoish wiki for some background to this post.

Let’s establish some basics. Content, as I think of it, in the context of new/web/digital media, is all of the stuff we read and right on the web. Documentation are those texts which supports the use and creation of technical tools, and explains technical concepts. While obviously read literally, documentation is content, but I think the way we’ve come to understand other kinds of digital content provides an incomplete basis for understanding how technical texts are published and consumed on line.

Consider the following assumptions that we can make about most forms of content on the web:

• The basic unit of content is pretty short. 1000-1500 tops is the upper boundary for most blog posts and articles, and while some kinds of content can sneak by with slightly longer units--particularly in well structured contexts--these are exceptions.
• Most content on the web is time-sensitive. While everything gets archived, the focus of publication is often on volume, which increases the chance of producing something that “goes viral” and gets a lot of attention. All other things being equal, the most successful on-line publishers are the ones with the shortest publication processes and the most regular publication cadences. After a short period of time, what’s in the site archives is probably largely irrelevant.
• Given the way that some content competes with other content, success is often determined by specialization, and the tightness of focus. It’s easier to be the loudest voice in a very small room than it is to be the loudest voice in a large room or a lot of small rooms. Content, thus, needs to be very focused and address very niche interests.

in contrast:

• Documentation texts tend to be pretty long, and while there are some “quick reference”-scoped texts, and some very complete texts that are quite long, on average documentation is substantially longer than “content.” This means it needs to be produced differently, and we can expect different usage patterns.

• In general people don’t read documentation. This isn’t just that people don’t “rtfm,” but that if generally people’s interaction with a piece of documentation begins with a specific question or problem. They don’t say “oh, that manual for $xvz product looks interesting, i’ll read it,” and i think the “i should read the documentation for $uvw before i begin doing $task,” is much less common than we’d like to think.

  People read documentation very tactically. So it’s important that documentation exist and be complete, but we should have no illusions that people read any documentation from beginning to end as “clean slates.”

• Documentation is always already very tightly focused, unlike content. While some technical publishers may publish “second hand documentation,” and thus be able to focus on documenting different aspects of the user experience, most documentation producers must aim to cover as much as possible, and allow users to find and take advantage of whatever information that is most useful for them.

As a result, it’s absolutely crucial that we don’t think of and produce documentation as being crucial. I think treating documentation as something that needs to be compiled. is probably the first step in “doing right” by documentation. Build tools like dexy, similarly, are great because they let writers and developers produce documentation in ways that make sense.

If you write or produce documentation--and better content as well--I’m interested in hear what you think about these issues. Onward and Upward!

One part of finding momentum and working to dedicate a bit of energy to some projects that I’ve been neglecting for a while. I’ve written a bit about finding the rhythm of my current routine, I’ve not written about what I’m actually doing. I hope this isn’t too boring for words.

Since the end of July, I’ve chosen to undertake a 2 hour each-way commute. Thankfully it’s all by rail, so the thought is that while I might not have a lot of time at home, I have more than enough time to get work done, of any sort, on the train. In practice my ability to actually get work done on the train is awful. In the past few weeks I’ve gotten a bunch better at this, and have actually managed to write fiction, get back on the blogging bandwagon, and stay on top of emails, and even reading a bit.

Here’s how a typical days works. I have a 20 minute train ride, a three to five minute walk, a 20 minute train ride, 10-15 minutes of waiting, and then 40 minutes of a train ride. Reversed in the evening. The first/last trains are sometimes standing room only. I try and spend the second and third train in the morning on the computer writing blog posts and fiction. If I can write first thing in the morning I can take it, but I always think about what writing needs to be done. On the way home I wrap up loose ends, read email, and at least a couple of days a week I get some knitting try to read and knit.

And it works. Most of the time, or at least enough of the time, for me to be able to notice that I’m actually doing things. I think as much anything, I’ve been able to get a much clearer idea of what I can expect to accomplish in any given time span, which makes it much easier and more productive to make a todo list. I think the main purpose of keeping a todo list is to focus working times so that I never find myself thinking “I have a few free moments, what should I work on today,” because the list tells me these things. If I know how much time I have, about, I know how to best spread out tasks for optimal working without ever needing to waste time wondering what I ought to be working on. It seems to work.

In the end, the novel keeps getting longer and closer to the end. I’m starting to think that I may be a bit too ahead of myself on the blog. My sweater-in-progress gets longer, and the progressing bar on my kindle progresses. That’s worth something.

I’ve been playing around with writing a story or a few stories about transpiration infrastructure,

I spend a lot of time on trains. And I in a part of the world where there’s a lot of transportation infrastructure, but most of it is nearly 100 years old. So while it’s nice that there are trains, it’s also apparent that the trains are designed to serve a reality which is radically different from the one that people today occupy.

I think I’m drawn to stories about people living in worlds that are out of sync with their reality. The story I’m writing now revolves around this idea, using the problem of relativistic space travel as a device to pull people “out of time,” but I think there are ways that people’s relationship to their present is shifted without science fictional devices: by history, by political rhetoric, by development, and by illness.

The two ideas I’ve been playing with recently are:

• a story about the people who build some sort of railroad system on a new colony or outpost. I’m thinking Mars Trilogy (Robinson) meets Heart of Darkness meets Left Hand of Darkness (Le Guin).
• a story about a commuter on the Moon mid/post-Accelerondo. Sort of “Philadelphia in Space.” This is probably more of a short story/vignette sequence, and I have a little bit sketched out but it’s all in first person and I need to make that not be the case.

I’ve written between 100 and 300 words on this novel that I’ve been working on for two and a half years, for the past two weeks. After too many months of writing much less than this, and I’m pretty sure that it’s been much longer since I’ve been able to write this regularly (regardless of length) on a fiction project. This feels amazing, and for the first time in forever, I feel like a real writer. Which is kind of an amazing thing.

This Project; My Life

Even when I’m not writing fiction, I’m pretty prolific, so I suppose, I almost always feel like a writer. At the same time, writing endless emails and writing stories is very different. I think it takes a few months for life to settle down, for new routines to establish themselves, and the for habits to emerge that make it possible to write. This project has lingered along for way too long, and while I’m still interested in it, and interested in the ideas that it raises, I’m in a very different place in my life right now, and I would like to put this to bed so I can work on other things.

I want to write short stories, and work on pulling together application together for Clarion (or Viable Paradise?) for 2012 or so. And I have this story that I’ve been pondering for months about non-normative family geometries and adult relationship structures (in the way that Le Guin’s Left Hand Darkness addressed similar issues regarding gender.)

I’m putting together the final scenes of Chapter 10. I think I have another week or two here. Then there’s a lot of explosion and general climatic goings on in 11, and I’ve only planned 12 chapters. Actually in a moment of foresight, I planned out 11 chapters, skipping Chapter 9 and leaving the words “overflow here.” And really, the prospect of being able to write the awesomeness that is Chapter 12 has been the main thing that’s kept me going through all of this.

Art as Work; Art as Habit

There are two parts of this. First, I think art isn’t the kind of thing where you take raw talent, and wait for divine inspiration, and find quality creative work. No. Doing art is about participating in conversations, about pushing yourself to create better work, learning skills, and figuring out a way to make a living doing your art (or something related) so that you’re able to continue to be involved and productive. Art is hard work, and perhaps that’s (part) of why it’s so important. I’m okay with this.

I am also a very strong proponent of the idea that being successful as a creator/writer/artist--is less about having “great days” and more about getting a certain amount of writing done every day. The hardest part of writing is always in getting started. Once you have a little momentum, it’s easy to write a modest amount every day, and that’s the kind of writing that adds up and makes novels.

At least that’s the plan.

Yesterday, I posted over at Critical Futures the second of, an apparent, series of four posts on dexy. Dexy is cool because it’s a pretty nifty tool for doing documentation in a new and potentially very powerful manner. While I think playing around with Dexy is cool and important (and I’m having fun tinkering a little, seeing the world in a slightly different way and then running away to absorb and re-assess) it’s also very important to think about the reasons why tools like Dexy are incredibly important.

Read on for: `Dexy and Literate Documentation <http://criticalfutures.com/2011/01/dexy-and-literate-documentation>`_

Also, as part of this post and series (archive recently updated!) I’ve been developing a technical writing section of this wiki, which has included a couple of little pages and snippets that I’ve been hanging onto for a while, and a number of pages that I think I’d like to write wiki pages on. These include three major issues in technical writing and the tools used to build documentation resources that build tools that yesterday’s addresses. They are: /technical-writing/atomicity or smaller “atomic” units of documentation, /technical-writing/compilation or generating documentation statically before publication rather than dynamically on view, and flitering as an approach to document generation.

I’d like to perceptively apologize if my blogging here is not particularly interesting, or topical except in a very “meta” sort of way. One of my primary goals for tychoish.com-as-a-wiki is to be able to keep track of and document the work that I’m doing on line that isn’t necessarily blog-post related. Blogging is great, but it’s hard to balance writing blog posts and providing a good media outlet and the kind of work required for developing wiki pages and moving forward on other sorts of projects. These posts, in addition to spreading links, and offering short partially formed thoughts, will likely serve to draw attention to various things I’m working on.

The idea of wiki gardening isn’t new, but I like it. Wiki’s are so simple and so easy to create that the only thing you can really do to cause a wiki to fail is to neglect it. Not that the proper care and feeding of a wiki isn’t challenging, but it is simple. In any case I suspect many of the meta posts will be “gardening” posts in the sense that they’ll draw attention to recent edits of wiki pages and note the new and developing pages in solicitation of your contribution.

Shovels up!

See “Why The World Is Ready For Dexy” for the lead into this post. The short version: most tools for building documentation are substandard, and most attempts at “fixing documentation processes” are flawed. But there’s this new project called “Dexy” that is doing something that is pretty exciting.

Basically, Dexy is a text filtering framework, you write documentation, code samples, and code, and then you tell Dexy how to stitch everything together, and bingo. It’s success, or potential success, is built around its simplicity and flexibility.

This model Dexy proposes something called “Literate Documentation,” which is a cool concept, which expands upon the notion of “literate programming,” both concepts require a little bit of unpacking.

Literate programing is the idea that code, documentation, and all specifications should be contained in one file, with blocks of machine readable code and human readable text should be interleaved with each other. Literate programming tools, then take this “mega source” and build programs that do cool things. There are a number of literate programming tools, and some notable programs that are written in this manner, but it’s not particularly popular: code and text tend to flow in different ways, and a manageable literate programming text, is often not particularly maintainable software.

Literate documentation, on the other hand, as implemented by Dexy is documentation where the documentation is compiled from an amalgamation of text and code which can be run and tested at build time. You write code snippets and documentation snippets, and a tool like Dexy takes all of it, runs the code and stitches together a document out of all the pieces. Then, anytime you need to make a change to the code, or the text, you rerun Dexy and the documentation mostly tests itself. Good deal.

I think it’s not yet obvious if Literate Documentation will actually be a “thing.” It’s a great idea but, like literate programming, it’s unclear of how this kind of practice will actually catch on, and how useful/feasible writing documentation will be in this manner. “Dexy the method” may or may not find greater acceptance, because “Literate Documentation” may depend on developers writing documentation. At the same time I think that “Dexy the tool,” is certainly a valuable contribution to the field of technical writing. Nevertheless, I think there are some important things about the way Dexy works that are worth extrapolating.

(Links to `tychoish wiki <http://tychoish.com/readers-guide/>`_ pages concerning `technical writing <http://tychoish.com/technical-writing/>`_ in some state of existence.)

• Atomic Documentation. Dexy reinforces the idea that documentation should be written in very small units that are self sufficient, and address very small and specific topics, questions, and features. The system which builds and displays documentation should then be able to either usefully present these “atomic” units or stitch more complete documentation together from these units. This makes documentation easier to maintain, and arguably makes documentation more valuable for users.
• Compiled Documentation. The “end-product” Documentation should be statically compiled, unlike (most) web-based content that is dynamically generated. This allows writers and teams to verify the quality of the text prior to publication, and allows the “build system” to automate various quality control tests. Documentation is particularly suited to this kind of display generation because it changes very irregularly (no more than a few times a day, and often much much less often.)
• Pipes and Filters. the process of publication can--like code--is basically passing text (and examples) through various levels of processing until the arriving at a “final product.” Dexy is very explicit about this and provides writers/developers a framework to manage a complex filtering process in a sane manner.

I look forward to thinking about these aspects of documentation and documentation systems, and about how writing texts with Dexy, or in the “Literate Documentation,” mode affects the writing process and the shape that texts take. I look forward to hearing your thoughts in the comments or on the wiki pages!

Here’s the problem: most of my computing happens on laptops which are both unreliably active (i.e. suspended) and also have unreliable network connections. (i.e. trains, etc.). I’ve done a lot of work to make it possible for my digital life to continue without interruptions. This includes writing cron jobs that exit before performing network intensive operations and making sure that most data can be downloaded and consumed in offline formats. But this is not quite ideal.

And I thought, “wouldn’t it be great if, I could just bundle up tasks into little chunks and throw them in a pile that the computer will process and perform when it can, so that I don’t have to remember to do things when I have a network connection and I can just drift in and out various states (active network, low-quality network, no network, and suspend/resume) without worrying about managing these states.” Sort of like a cross between cron and some sort of queuing/bus system.

Wait. A queue.

As many of you who are still reading know, the contemporary solution (and, actually historical as well, but we won’t get into that.) to enabling web applications to scale to be able to handle large amounts of work is to use queuing systems which allow applications to distribute and absorb bursts of activity, by spreading work out between high and low utilization periods. Basically: if you don’t have to do everything all at once, split everything into little “atomic” jobs, make a list and then process, and do jobs as you can until everything is done.

These are high performance systems, meant to handle nearly incomprehensible amounts of activity, but the idea is the same: I (and perhaps you too?) need a system that can figure out what state a machine is in and can save tasks and run them when the conditions are right. Simple, right?

Anyone want to work on this with me? Come on, it’ll be fun!