Updates: Tech Writing and Wiki Gardening

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.…

Keep reading

Dexy and Literate Documentation

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.…

Keep reading

Make All Novella

(Note: I was going through some old files earlier this week and found a couple of old posts that never made it into the live site. This is one of them. I've done a little bit of polishing around the edges, but this is as much a post for historical interest as is a reflection of the contemporary state of my thought.) When I decided to publish my novella Knowing Mars, I decided that I wanted to use my existing publication system and that I wanted to automate the process of generating of all the necessary versions that made it possible to keep my original files in sync, without needing to duplicate effort.…

Keep reading

Link Storm

I have a bunch of links that have been hanging around too long, that I'd like to share with you, so here they are. Enjoy! Distrust Simplicity is a great short form blog, that I'm really liking. The Singularity Summit is a cyborg/futurist event that a reader wrote me a note about a rather long time ago. If you're interested in the singularity and issues and ideas related to that. Hypo a literate programing (with org-babel) based asset management system for game development.…

Keep reading

Laptop Queuing System

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.…

Keep reading

Why The World is Ready for Dexy

At one time or another, I suspect that most programmers and technical writers have attempted to "fix" technical writing in one way or another. It's a big problem space: Everything, or at least many things, need to be documented, because undocumented features and behaviors cause problems that *one really ought not need to review the source code and understand the engineering to fix (potentially) trivial problems, every time the occur. The people who write code are both not suited to the task of writing documentation because writing code and writing documentation are in fact different skills.…

Keep reading

Wiki Blogging

I'll probably do a fair piece of this "metablogging" thing here, and I'm sorry. Also, I totally intended for rhizome to be a much shorter form blogging project, and while the posts are shorter here than at critical futures, they're not exactly short, and I'm not exactly as prolific as I might like to be. I think I might just be somewhat long-winded. I've also found that I've mostly not succeeded as using the wiki functions.…

Keep reading