Recent Posts

Lose Developers and Alienate Everyone: How Not to Write Docs

3 minute read

You know, there are so many projects out there with great documentation. To make your docs stand out, why not make them crappy instead? Just think of the buzz you’ll get on Twitter and all the questions on Stack Overflow trying to find out what anything means! And who needs GitHub Stars when you have an issue queue filling up with basic questions?

So, without further ado, let’s Think Different, Be What’s Next, and Disrupt your Docs!

Note: The tales of woe below are all true. I’ve personally experienced them…and worse.

1. Sesquipedalian Loquaciousness

Your team has put so much effort into developing its own jargon and slang. Sure, some may say it looks like buzzword bingo or an explosion in a dictionary factory, but what do they know? They wouldn’t appreciate your Sesquipedalian Loquaciousness if it bit them on the nose.

Saturday Morning Breakfast Cereal
Thanks to SMBC for the comic!

Your long words and purple prose ensure everyone can see how smart you and your development team are, and with such an intelligent team they’re bound to want to use your code!

Seriously though… Not all of the folks reading (or contributing to) your docs will be native speakers of your language. And what are people more likely to Google? projectname API or projectname meta synergy protocol?

2. Mark Down? Who’s He?

Everyone should be free to use the authoring tool of their choice. After all, what’s the point in Free Software if you don’t have the freedom to write your docs in Scrivener, Apple Pages, Microsoft Word, or PowerPoint. As long as they get the files onto Github it’s all good!


Or why not try Lotus Word Pro?

Seriously though… I’ve had to deal with Apple Pages files being uploaded onto repo’s before, and that’s by members of the internal dev team. Using a Linux box, they’re a pain in the neck to open, and how the hell are you going to do version control on those things? That’s not to mention the time a junior dev uploaded Markdown pasted into a Word file, which they then renamed to have an .md extension…

3. Yeet those 🗎 and smash that “Clone or download” button, fam 😎

Your project is cutting edge, so your docs should reflect that. No need for any of that frumpy old English - Emojis work across languages and have no ambiguity, and if you want to attract a cool, hepcat group of rockstar ninja hackers you need to speak their language. Not employing any 13 year olds? Just ask your niece to yeet something up for you! And don’t forget those amazeballs acronyms LOL!


Yes, that’s exactly what it means…

Seriously though… Don’t. Just don’t. Nobody hits up your developer docs to be entertained. And many devs are terminal jockeys, and emoji’s don’t translate well to that environment.

4. A Thousand Eyes Make All Docs Perfect

Your docs are the lifeblood for your ecosystem of developers. And nobody wants dirty blood, do they? Best to have your team of experts check everything three or four times before uploading, and then get final approval from the CEO before opening your docs repo. Developers won’t mind waiting a few weeks (or months) for a basic API reference as long as every T is crossed and every I dotted.

Seriously though… The perfect is the enemy of the good, and there are a lot of good projects out there catching the eyes of developers. Release early, and release often. It’s better to have some basic docs out there that do the job, rather than a perfect all-singing, all-dancing ensemble that’s already out-of-date by the time its released.

5. If You Truly Loved Me, You’d Put the Work in…

You don’t want just anyone contributing to your project or using your tools. Only the best are good enough - and your application and vetting process ensures that only the best applicants will get that coveted repo access…any day now. Be sure to ask them for their LinkedIn profile (so you can see they’re a true professional), their phone number (because data leaks and phishing aren’t a thing), and a convoluted password (because those docs are precious, damnit)

Seriously though… Developers are typically looking at several ways to get the job done, and adding friction will just push them elsewhere, regardless of how great your project is.

Next Time

In the next post we’ll be looking at best (and worst) practices for documentation platforms. Stay tuned!

Bent Out of Shape - All the Ways (so far) I’ve Screwed Up with Nitinol

4 minute read

I recently got my hands on some nitinol wire for a project I’m working on. Here are my misadventures in trying to work with the damn stuff.

The Project: Biomimetic Butterfly Brooch

I like butterflies. I like looking pretty. I like making stuff. So I’ve decided to make a butterfly brooch that’s hyper-realistic and fools the eye into thinking it’s actually alive.

To do this, I need the wings to flap and the antennae to move. And since it’s supposed to more or less life-size, I don’t have a lot of room for battery power or motors. I’d seen nitinol before and thought it’d be a fun and interesting solution to the constraints. In short, nitinol is a kind of shape memory alloy. It “remembers” a shape, so when you deform it then add heat or current, it’ll bounce back to the shape it has in its “memory.”

So…is it a viable solution? The jury is still out on that one, at least for the next few days. Let’s wait and see!

Getting the Nitinol

I found a supplier on Taobao, the store that has cheap everything. If you’re outside China you may want to check out eBay or AliExpress. There were two main types on nitinol on sale:

Pre-shaped Nitinol

Often for use in magic tricks. For example, “guessing” your mark’s card and then making this seemingly innocuous piece of metal spring into the shape of the seven of diamonds.

Raw Nitinol

In the form of wire. Since I have a specific shape I want to make, I bought a meter of 0.3mm nitinol wire for about 7 RMB (about 1 buck USD at the time of writing)

First Reactions

Wow. This stuff is springy. And totally unbendable. And it’s so damn thin that when I put it down, I can’t find it to pick it up again. Also, it’s not magnetic. That’s a big plus, since I may use strong magnets as a fastener for the brooch.

Forming the Shape

Before forming the shape, nitinol is still in its superelastic (springy as hell) form. To give it shape memory, we need to add heat. I didn’t really research this bit enough, but just went ahead and started experimenting by clamping a small piece of nitinol wire in some helping hands, and making it all hot and stuff.

Things I tried:

  • Soldering iron: Not hot enough
  • Hot air gun: Not hot enough
  • 4 x AA batteries: I’d read that current would do the job, and someone had used 4 x AA’ to do it. I didn’t read carefully enough - they’d only used the AA’s to bring it back to it’s remembered shape, not form that shape in memory

At this point I did a bit more research (i.e. did more than impatient skimming) and found out I need a temperature of 500 to 550 degrees Celsius. I figured it’d be better to go too high rather than too low. I’d already seen what happened with too low temperatures (zip, nada, nothing), so figured I should at least try extreme heat if only to see what happens.

So I pulled out the trusty blowtorch and proceeded to NOT set myself aflame. Small victories and all that.

This time I actually made the damn thing bend. Bending a bit of wire doesn’t seem like a big deal, but I’d already invested half a day in this so yay me I guess. I took it out of the clamp and quenched it in a cup of cold water.

!{}(images/butterfly/nitinol_clamp.jpg)

So, the shape was set in memory…or was it?

Deforming the Shape

Now that the wire was bent, it was time to unbend it to test if it could bounce back. I made a few test pieces - just bits of wire with a kink to test the concept:

  • Half of them: I bent into a different shape no problem
  • Half of them: SNAP! Broken in two

Reforming the Shape

I’d read that just putting the wire in hot water should bring it back to it’s remembered shape. I schlepped up to the hot water machine, heart aflutter. Could all this frustration pay off at last? Had I actually not wasted a whole day obsessing over a kink in some wire?

I put the bent up wire in the cold water and watched intently, waiting for it to reform. Seconds ticked by. And…nothing. It just sat there, like a piece of wire that just sits there. Ugh.

How’d I Mess Up?

It was likely because the torch was too hot. 1,000+ degrees, while nitinol needs about 500-550. Even covering the oxygen holes to get a cooler flame on the torch didn’t really work, mostly because we used a rubber band and it was hardly uniform.

Back on the Wagon

What’s next? I’ll head back to the hackerspace and try:

  • Plan A: Running enough current through the nitinol to heat it enough to set a shape. I’ll use a PSU to start low and ramp up.
  • Plan B: I’ve ordered a different head for the torch, one with a knob that allows me to control the amount of oxygen, so I can get a nice yellow flame instead of a fierce blue one.
  • Plan C: Screw nitinol. I’ve ordered some tiny DC motors, and will 3D print some kind of ornithopter mechanism to make the wings on the butterfly flap.
  • Plan D: A friend mentioned using a kiln at a ceramics factory for heat setting a shape in nitinol. This may take time and money to set up though, and I’m not sure it’s worth it at the prototype stage.

Some MediaWiki Tools

less than 1 minute read

I’ve been working on a couple of tools for MediaWiki over the past few weeks:

  • MediaWiki_Unembed: Takes a MediaWiki file with other wiki pages embedded inside (via the tag) and unembeds them, resulting in a MediaWiki file with all the embedded content inline
  • MediaWiki2Book: Uses Pandoc and some nice templates to convert a MediaWiki page to a good-looking PDF

Unfortunately I’ve had trouble with API access on the MediaWiki instance we’re running, so you’ll have to manually copy/paste your MediaWiki page’s wikitext into a text document before runnng mediawiki2book

Links of the Day

less than 1 minute read

Focusing On The It In Diversity

2 minute read

How many times have you crap like this?

"I wouldn't trust a woman to code. Women in the tech industry are just a distraction to real programmers"
"What would the gays know about technology? They should stick to hairstyling"

Since this is a family-friendly blog, I’m really having to hold myself back from using the ‘BS’ term to describe the above things I’ve heard in the tech industry. I’ll just call them complete and utter nonsense, poppycock, and rubbish, at least until I find a more offensive but publishable world.

Diversity has been on my mind a lot lately. Things have slowly been getting better in many parts of the world, but sometimes its a case of two steps forward, one step back. However, today I’m focusing mostly on the STEM field, especially that of computer science.

From tech companies, university comp.sci departments, and makerspaces, our field has always seemed…blokey. There are a lot of dudes, a lot of casual sexism, and not many people are exactly rolling out the red carpet for diversity.

Which seems insane to me. Some of the best coders, managers, educators, technologists and scientists I know are people of color, women, or LGBT. And it’s not just true today. Our whole industry (and the modern world) was built with the help of these folks who are just a minority in our field today.

Just look at:

  • Ada Lovelace wrote the first computer programs in the 1840s, before programming was even a thing.
  • Alan Turing, who played a major role in shortening World War II with his work on technology, was hounded by the British government for his homosexuality and eventually took his own life.
  • Katherine Johnson, Dorothy Vaughan, and Mary Jackson, three women of color who computed the trajectory for America’s first trip to space, back when NASA didn’t even trust computers.

And that’s just a few. I haven’t even mentioned Magaret Hamilton, Grace Hopper, or Hedy Lamarr!

We’re in a world where the very technologies minorities invented are being used to harass and oppress them. And usually the person sending those racist, homophobic, or misogynist tweets has no idea about the wonderfully diverse history of our technology that led to the invention of the very phone they’re tweeting on.

Computer science has NEVER been a club just for straight white dudes. I’m planning to talk about this a lot more in the coming months and do what I can to make things better. As a good start, I’ve been reading this awesome diversity list from Folks who Code on Github. I recommend you check it out!

On Learning Machine Learning

1 minute read

Machine learning has a lot of buzz these days, and with good reason. But getting into it isn’t a simple task. Here’s what I’ve discovered so far:

Pure or Applied?

Applied machine learning is about using it to actually do stuff in the real world. Pure is more about learning the theory behind it. While it’s good to have at least some grounding in algebra and matrices before jumping on the latest modules, there’s nothing quite like getting your hands dirty.

I’m already proficient in Python (the de facto language for a lot of machine learning projects) but even then, getting my hands dirty took some work before I got a handle on what was going on. Watching some tutorials on Numpy (a module for dealing with numerical matrices) and Pandas (a module for tabular data representation helped a fair bit.

Tensorflow? Keras? Scikit-Learn?

I’ve dabbled in all three, but sticking to Scikit-learn for now. It seems the most straightforward by far, since you’re working with pre-existing models, and it comes with several datasets by default, all of which are already processed for easy use by the module.

Tensorflow is a lot more low-level, and while Keras is high-level it’s more about building your own models rather than playing with existing ones.

Once I get a better grip on models I plan to look at the other options.

Python 2 or 3?

Different tutorials use different versions of Python, and these different versions really are different. Even dividing numbers will return different results depending on your version! Not to mention needing parentheses with the print() function in Python 3 (which I’m constantly forgetting about – old habits die hard!)

Jupyter Notebook

Aaah, our old friend Jupyter. I’ve been using the notebook more and more, using markdown cells to paraphrase tutorials in my own words as I go through them. Plus, embedded graphing via matplotlib helps a great deal. Just make sure you install the kernel for the right Python version!