Buildcloth v0.3 Planning

I spent a lot of time at the end of the summer working on finishing out the basic buildcloth functionality, and haven't really gotten the chance to use it properly. There were some flaws: a dumb oversight means that the hash-based dependency checking doesn't work. Buildcloth is a bit complicated and designed for a general purpose. In practical terms, I made buildcloth to perform a task that I've been able to accomplish with 10% or less of the code.…

Keep reading

Documentation Tooling

I've spent a little bit of time building some non-critical tools for my teammates on my work project, which has got me thinking about tooling for documentation systems. This collection of tools is something that we've started to take for granted, but I think it's pretty novel and worth talking about a bit more. Documentation toolkits, traditionally refer to the system that deals with the production of the documentation for end use, which typically means taking the source text and rendering it into web sites, pdfs, ebooks, and embedded "online help" text.…

Keep reading

Large Sphinx Deployments

I use Sphinx a lot. Both in the sense that I have easily a dozen active (or reasonably so) projects that I maintain and work with on a regular basis. Sphinx is great, and I feel safe asserting that it's probably the best documentation toolkit in existence and more generally the best tool kit for the production of structured text. There are flaws. I've written here before with greater and lesser descriptions of the pain points of Sphinx.…

Keep reading

Uphill Forever

In many ways this is the follow up to hard is good and the post I promised recounting the lessons of the buildcloth v0.2.0 release This release of buildcloth is in some ways, the first real piece of software I've written from the ground up. I've written a bunch of code, and I've implemented a decent amount of functionality as extensions and additions to other programs, written some very small programs, and written an endless number of throw away scripts, but never something quite on this scale.…

Keep reading

Buildcloth v0.2.0 Release

Today I did a (slightly) more formal release of a software project that I've been working on pretty consistently for the last two months. It's an extension or elaboration on the buildcloth, and is the groundwork for some other projects I've been working on. While there are some new fixes and improvements to the initial meta-build tool components of the project as I'd been working on 5 months ago, this one goes even further and includes a complete build automation tool.…

Keep reading

Hard is Good

In the hard part of software you could easily chose to read the word "hard" as "sucky," which makes it seem like a big whine on the topic of "polishing your work is hard and annoying," but really, that's unfair. I think it's probably better to read the word "hard" as "important" rather than "sucky". While you may be able to get someone to try your software on the basis of its core implementation or design, people keep using software because it's reliable (i.…

Keep reading

The Hard Part of Software

I've been writing build system tool that allows users to specify concurrent build processes using a lightweight, Python-based system that minimizes overhead. Progress is decent. I hope to use this to replace a hodgepodge of fabric and Makefile for my work and personal projects. I have a decent spec (3 hours), an initial implementation of the internal parts (3 hours,) a good first draft at a command line utility (1.5 hours,) internal/APO documentation (10 hours,) and none of the unit tests and procedural and conceptual documentation.…

Keep reading