I’ve been thinking recently about the way that my interest in writing and publishing blog posts has waned, and while there are a lot of factors that have contributed to this, I think there’s a big part of me that questions what the purpose of writing is or should be, and because I mostly write about the things I’m learning or thinking about, my posts end up being off-the-cuff explanations of things I’ve learned or musings on a theoretical point which aren’t particularly well referenced, and while they’re fun to write and useful for my own process they’re not particularly useful to anyone else. Realizing this puts me at something of a crossroads with my own writing, and has me thinking a lot about the practice of citation.¹

Mechanically, citation anchors text in relationship to other work,² but it also allows discussion to happen in and between texts. Also, the convention for citation in the context of informal writing is a link or an informal reference, so it’s difficult to track over time, and hard to be systemtic in the way that one text interacts with its sources.

Blogs bring out confessional writing with ambling³ structure and the freedom to say just about anything, which I have found liberating and generally instructive, but it’s also limiting. For writing that comes out of personal experience, it’s difficult to extrapolate and contextualize your argument, or even to form an argument, particularly in the context of a blog where you’re writing a larger number of shorter pieces. It’s also probably true that by framing discussions in personal experience its hard for people with different experiences to relate to the content, and more importantly the concepts within.

I’m not arguing against journaling: journals are greatgreat, but sometimes, I think journals might be best unpublished. I’m also not arguing against the personal essay as a form: there are many topics that are well served by that genre of writing. I do want to think about what else is possible⁴ and how to write things that are stronger, more grounded, and easier to relate to and interact with. I think more citations and references are the key, but I’m left with two problems:

1. Style. There aren’t great conventions for referencing things in informal writing. Throwing a link in the right context works, and is clear, but it might not be enough as it’s hard to know what’s a citation-typed-reference and other kinds of links. Also links don’t hold up well over time. The more formal approaches are rooted in out of date technologies and tactics. Citations often reference page numbers, footnotes don’t often make sense in informal situations,⁵ and bibliography conventions are mostly non-existant.
2. Tooling. I’m pretty sure that well cited texts are well-cited, because their authors have great memories for things they’ve read, but because researchers often have tooling that supports managing a database of references, notes and bibliographic information. If you have a record of the resources you’ve read (or otherwise consumed), it becomes easier to pull out citations as you write and edit.⁶

Neither of these are insurmountable, but I think would require a good deal of work both on figuring out better citation formats and patterns, as well as developing better tooling. I don’t have answers yet, but I do want to think more about it, and probably play with writing some tools.

I’ve posed about some of these projects before, and I used to regularly post little overviews of the things that I’m working on. But I’ve not done a lot of this recently. Time to do some back fill.

I think it’s probably good to take a step back from time to time and inventory and evaluate the priorities of various projects. Not to mention the fact that I usually say “I’m not really doing much these days,” when this isn’t really true. Here goes:

Mango

This is a project that is private, at the moment, because its mostly useful as an experimental piece of testing infrastructure for work. The idea is to use the same underlying infrastructure to start, stop, and configure processes, but provide REST and command line interfaces for all of these operations.

We have a lot of distinct software that does this internally and it’s always fragile and limited. While grand discussions of code reuse are sort of silly, in this case, it’s a bit annoying that we’ve reinvented this wheel a dozen times… And have to make different changes to a dozen tools as configurations change.

This was also my first project written in Go, which means its been a great learning experience and the place where a number of other Go packages that have become useful in their own right.

Future work:

• Write all the tests.
• Make the REST interface feature compatible with one of the legacy tools it aims to supplant.
• Make a new REST interface that’s more sensible and might be easier to use in more circumstances.
• Figure out better ways to block for the appearance of synchronous operations, despite the fact that internally the operations are non-blocking.

Gimlet

Gimlet Blog Post

Gimlet Github

This is really just some convenience work to make it easy to build REST interfaces in Go, without needing to suffer through tools that are designed to support complete “full-stack” web applications. It’s built on the same Negroni/Gorilla Mux stack that I think everyone uses, and it’s very net/http compliant, but with an API that makes it easy (even fun,) to provide high quality JSON+HTTP interfaces.

It struck me, when working on part of Mango, that this chunk of the code didn’t have anything to do with the actual core application and was all about getting a REST-like application to happen. So I split that out, for everyone’s pleasure/suffering.

Future work:

• Documentation.
• More tests.
• Exposed API stabilization and versioning.
• Develop story for authentication, sessions and SSL termination.

Grip

Grip Blog Post

Grip Github

Grip is a logging package for Go that attempts to resolve my constant feelings of “I miss x feature of the Python logging package.” It’s not feature comparable with Python logging (but that’s ok,) and since I was working on writing a logging package, I got to add some nifty features.

Future Work:

• More documentation.
• Better examples, and potentially support for “print this message x% of the time.”
• Support for logging to conventional syslog sources in addition to systemd’s logging.

Archer/Dropkick

I’ve wanted to work on a tool to unify a number of personal operations and scripts in a single system and tool. The problem that I’m trying to solve is that I have a number of different computers that I use with some frequency, including laptops, desktops, and a number of servers, and test systems, and I want to be able to describe their configuration, and synchronize files and git data between machines with ease.

My first approach was getting a bunch of random system setup scripts out of a makefile and into a configuration file that a Go program knew how to read and process, and then to expand from there.

I haven’t gotten to the git repository management stuff, because I was working on the Gitgone project.

Future Work:

• add better support for creating and managing containers and images using systemd-nspawn and docker.
• support for setting up git repositories
• support for syncing automatically (i.e. dropox-like functional it -> dropkick).
• report status of repositories via a REST API
• triggering syncs on remote systems.

Gitgone

Gitgone Github

The idea here is to provide a consistent and full featured way to access and interact with git repositories from Go without needing to wrap the git command yourself (or worse, learn the ins and outs of the git2go). This is largely modeled off of a similar project I did as part of libgiza that does the same sort of thing for Python repositories.

The cool thing about this project is its build abstractly so that you can use one interface and switch between a libgit2 implementation and one that wraps the git command itself.

Future Work:

• complete implementation using libgit2
• write more extensive tests.
• add support for creating repository tags.
• provide access to the log.

Novel Project

I’ve been, sporadically, working on notes for writing a new novel. It’s not going anywhere fast, and I’m not even to the point. where I’m outling plot.

I’m trying to tell a story about urban development and how smaller local communities/groups participate in larger communities/groups. How does urban development in place a, impact nation building more globally, and what does this all look like to people as they get to work in the morning, and have to build neighborhood institutions like gyms and restaurants and grocery stores.

But there’s a lot of work to do, and while thinking about the project is fun, there’s a lot of work, and I feel like I’m not ready to commit to a writing project of this scope and, I’m not sure how publishable this project will be (and furthermore, even if its' publishable, will I be willing to do all of that work.)

Software projects are much harder to justify and prioritize than writing projects.

I recently took some of my writing time to create a makefile (Novel Makefile) to manage work I hope to be doing on a new novel project. I’ve started outlining and researching the story in earnest after having spent the past few couple of years talking about it, and I think writing will commence soon. In another post I’d like to write up some thoughts on the tooling and technology of writing non-technical/non-manual long-form.

This post, drawing from the spending some time buried deep in production is about the state of (conceptually) longer form work in digital mediums. Or, at least a brief commentary on same.

The tools that I use to write technical materials do all sorts of cool things, like:

• provide instant cross referencing,
• generate great indexes, and
• automatically generate and link glossaries.

This is not particularly unusual, and in fact Sphinx is somewhat under-featured relative to other documentation generation systems like DocBook.¹

And yet people publish ebooks that virtually identical to paper books. Ebooks seem to say “*this electronic book is the best facsimile of a paper book that we can imagine right now,*” while totally ignoring anything more that a *hyper*text rightfully might be.

I enjoy reading ebooks, just as I have enjoyed reading paperbooks, but mostly because ebooks basically are paperbooks. I’ve written posts in the past challenging myself,and fiction writers in general, to actually do hypertext rather than recapitulating prior modalities in digital form.

At various points I’ve thought that wikis might be a good model of how to do hypertext, because the form is structurally novel. Any more, I don’t think that this is the case: wikis are unstructured and chaotic, and I’ve come to believe that the secret to hypertext is structure. There are so many possibilities in hypertext, and I think much experimentation in hypertext has attempted to address the chaos of this experience. This does serve to highlight the extent to which “the future is here,” but it obscures the fact that structure makes narratives understandable. Think about how much great, new, innovative (and successful!) fiction in the past decade (or so) is not structurally experimental or chaotic. (Answer: there’s a lot of it.)

The not-so-secret of hypertext, is (I suspect,) tooling: without really good tools the mechanics of producing a complex, interactive textual experience² is difficult for a single writer, or even a small group of writers. Most tools that manage the publication and writing of text are not suited to helping the production of large-multi-page and mutli-component texts. One potential glimmer of hope is that tools for developing programs (IDEs, build systems, compilers, templating systems, introspection tools, pattern matching, etc.) are well developed and could modified for use in text production.

The second non-so-secret of hypertext is probably that hypertext is an evolution of text production and consumption, not a revolution. Which only seems reasonable. We have the technology now to produce really cool text product. While tooling needs to get better, the literature needs to do some catching up.

Lets start making things!

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!

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.

I’m working on the final touches of a treatise on Systems Administration that I’ve mentioned in passing here before. I hope to have this project up on a web-server near you (near me?) in a few months. Because I’ve had a lot of fun working on this project, I decided that it would be cool to do a similar project on another topic dear to my technical interest: Computing Literacy.

Computing literacy? Isn’t that a little *early nineties* for you and or everyone?

Well yes, I suppose, but don’t think that the improvements that have aided the adoption of technology in the last 20 years have necessarily raised the amount of computing literacy. In fact, it would not surprise me if all of the abstraction and friendly user interfaces make it more difficult for users to understand how their computers actually work.

Because their computers play such an important role in everyone’s life and work, I suspect that there are a lot of folks who don’t know how these things work but want to learn. And the truth is that there aren’t a lot of resources around for people who aren’t already tinkerers and hackers.

This is where I fit in: I can write a book-like object that provides useful information in an easy to understand way that technical people can provide their friends and family say things like “what’s a database?” or “what do you mean compiled?” or “what’s a server?” or “what is this file system thing?”

Are you so arrogant as to think that you can add something new to this subject?

I’m not going to develop new technology here, or suddenly make things easier to understand, but I think there’s a niche for computer users between people like me, who download putty on other people’s computers to ssh into their VPS server which hosts a VPN that their laptops are connected to, to ssh into their laptops to kill misbehaving X11 sessions (no really, I just did that,)* and most people who just know how to open MS word and send emails, and browse the web.

And I think that giving folks who are technically creative, intuitive, and curious a way to learn about their computers and technology would be great. Particularly in a way that doesn’t assume too much prior knowledge, or an interest in complicated math.

Ok, so you’re convinced that it’s a good idea, what’s going to be special about this?

First, while the material will not be so complicated or so novel, I think the presentation may be. Additionally, I envision this document as a useful reference for describing and defining basic computing concepts, to support more technical blog posts and articles.

Finally , I think it would be fun to do this book-like object in a more iterative style, relative to the Systems Administration book: I’ll sketch out the basics, put a disclaimer at the top about links breaking and then publish it, and publish changes and make the whole thing accessible by git..

Sound cool to anyone?

So there you have it.

Expect to hear more in the late summer or fall…

I’m stuck in an editing hole, and not only am I not editing the things I need to edit, I’m not getting anything done.

I’m at a point where I have about 25 things on my personal task list, and 16 of them are editing related tasks: edit the article in this file, edit this fiction, edit this documentation, edit these would-be-blog posts, and so forth. It seems like I went on something of a six month writing bender, and while I did a little bit of editing during this period, I have clearly fallen behind.

There are a number of factors:

1. I’ve been making a point of putting editing tasks on the todo list because I want to make sure that I actually finish projects rather than just abandon them. I’ve not been particularly good with follow through in the past few years, so that’s been a big personal improvement project.

The sad part is that my editing queue is probably 10-20 times larger, but I’ve got some projects on the less-actionable back burner.

2. I’m not a very good editor.

I’m awful at copy (or otherwise) editing my own work, and while I know that I’ve become better at this in the past few years. I still know that it’s not perfect and so it seems sort of futile, which makes it hard to get inspired to do editing.

3. I find writing to be rewarding, and given the choice I will probably always choose to write new stuff. While this is clearly a learned response to the kind of work, this doesn’t make the effect any less real.

4. I find editing to be really difficult work.

This is probably related to #2, but editing wears me out. I find it difficult to spend long periods of time editing, which makes it difficult to make any really substantial progress on the pile of editing tasks.

As a result, I take a long time to edit things, I’m most effective at editing in short bursts. I often want to break up longer editing tasks with other kinds of work just to keep a clean mind set. After a week or so of this, I have almost everything else done on the list, leaving me with a big pile of editing that looks even bigger for the lack of other things on the list.

So now, I’m trying the following:

1. I’m working on making editing tasks smaller, which will turn into more editing tasks, but it’ll be possible to face editing tasks in units less than 10 or 20 pages.

2. Make more tasks for other projects.

There are two ways to get stuff done: 1) You can be really focused and work on one project at a time until it’s finished, or 2) you can be working on a lot of projects in parallel and when you start to loose focus, you switch to another kind of project. The idea is that you end up getting more done because you’re being productive more of the time. I subscribe to the second theory.

Here’s hoping it works!

Onward and Upward!

There’s this saying, I traced it down once but have forgotten the source again, that before you can write anything good, you have to write a million words of crap.

Well I’ve done it. I’m guessing that most writers hit this number without much difficulty fairly early on in their lives/careers, but it’s hard keep records and do proper accounting of this data. And let’s be frank, it’s kind of a stupid thing to track. While I’m definitely a better writer these days than I was even 2 years ago, I know that I have a lot more to learn.

In any case, I have a firm account of a million words of crap that I’ve written in the last 10 years or so:

• tychoish.com this wiki, mostly rhizome accounts for a bit more than 800,000 words.
• I wrote a novel in 2002 and 2003 that now exists primarily as a paper volume in a zippered binder that I use as a foot rest. That was 100,000 words.
• Since September 26, 2011 I’ve written a bit under 101,500 words for my work. The number is slightly inflated on account of code samples, some repetitive sections, and a few articles that colleagues wrote that I did some significant editing/rewriting.
• Between June 2009 and May 2011, I wrote somewhere between 100,000 and 200,000 words for a previous job (again some measure of redundant content, other people’s work, and code samples makes this figure hard to track.)
• The Knowing Mars novella that I wrote between July 2007 and ~March 2008 is about 35,000 words.
• The novel that I finished the first draft of few weeks ago is about 85,000 words.
• I’m 35,000 words into the first draft of a technical book-like object.
• I have 10,000 words in a couple of other projects.

Which puts me way way way, over (what? 1,300,000.) I wonder when I broke the million word mark?

Some observations on writing.

• I still make all kinds of writing mistakes that I find embarrassing and difficult. Particularly with fiction (which probably only accounts for 200,000-250,000 words,) I feel incredibly clumsy.

• At the same time, as long as I have a clear idea of what a piece of text needs to say, I’m reasonably comfortable pulling together a draft without much fuss. Sometimes figuring out what I need to say involves a bunch of reading and long walk, but it’s possible.

• I’m getting better at writing less. Writing concisely is hard work and it’s easy to get into the habit of generating “word stew” that don’t say anything useful and are impenetrable to read.

• Writing is hard. I’ve always been an awful speller and I have some dyslexic moments, but--as longtime readers of the blog have surely noticed--I’m getting way better and writing cleaner copy.

  Editing other peoples writing on a regular basis has also been enlightening because it allows me to put things in perspective, and be able to see value in what I can do with words. Also it’s cool to be able to help other people write.

• This is totally a correlation, but I pretty much never write anything longhand, and I think I’m a better writer for it. The downside is that I’m incredibly dependent on my own computer and its setup to do anything.

Onward and Upward!