Documentation Inheritance

I'm interested in using metaphors and methods from programming and engineering to make documentation better. There are some obvious elements that are ripe for stealing in terms of process (scrum, iteration, etc.) as well as tooling (issue tracking, version control.) As I've continued to explore the connections and metaphors have become less obvious, but remain very helpful. Recently I've been thinking about and using the idea of inheritance to help address content duplication issues.…

Keep reading

Rambling about a Bug

I spent some time yesterday evening dealing with a bug in some code I wrote/maintain, and I thought it would be a good exercise to just talk about the issue, and approaches problem solving. This is both an effort to demystify the act of programming and debugging and a brainstorming exercise. I explained a bunch of the background in an external page, to make the content a bit more accessible.…

Keep reading

Write Sane Software

a checklist There's a difference between software that works, software that's brilliant, software that's maintainable, and software that's good. This is post that begins to enumerate the kinds of things that you can do as you write software to help make it sane and possibly good. This isn't about computer science, or really even about engineering principals. We all have a sense of what makes a physical object (furniture, buildings, electronics) feel like they are well made.…

Keep reading

Python Concurrency Rant

What and Why Concurrency is the term we use to think about operations that can happen at the same time. A computer program is just a list of operations that have some sort of ordering. If you run those operation in the order the programmer wrote them in, and the programmer wrote the right code, everything should work fine: If operation B depends on the outcome of operation A, then you just have to make sure that operation A happens before B.…

Keep reading

Structure, Documentation, and Poetry

At work I've introduced a new method for storing the content for procedural documents (i.e. tutorials/how-to guides/etc,) that is more structured. Rather than just writing a tutorial in a conventional way, we capture the steps in a specific structure that we use to generate the content in a specific way. The structure lets us do cool things with the presentation that would be hard to do well otherwise and help us focus theses kinds of documents on the core procedural or sequence-based nature of these documents.…

Keep reading

Practicing

In response to my Knitting Practices post, on Facebook my father commented "The word "practice" is apt. Is there an influence from yoga?" The answer is obviously "yes," though the route is somewhat indirect and travels through a story about programming. Stick with it for a little while. Generators and Python Memory Efficiency I was talking with a dancing friend about memory efficiency in Python programs, particularly with regards to loops and the range() function.…

Keep reading

The First Ankle Sock

I recently finished my first knitting project after my [[return to knitting|/knitting/a-knitting-practice/]]: a pair of ankle socks in a medium (for socks) weight yarn. The socks are plain and I'm pleased with the result, but there were some unexpected parts of the project, and some useful lessons: These Aren't The Socks You Meant To Make For the most part I'm interested in knitting pretty plain socks in plain (solid) yarn: probably even undated yarn that I can soak in tea or henna post-knitting.…

Keep reading