rant about software documentation / website trends

I draw my examples from open-source software (OSS) projects, but the latest webdesign trends in general really tick me off. I like objects that convey information well, and such objects we often find visually pleasing as well, but it we shouldn’t be sacrificing function for form, form should enhance function. Yes, I have strong opinions about design for conveying information.

Especially when I’m doing technical work, such as evaluating whether to adopt a piece of open-source software (for instance, try the picking a javascript tool to learn for the first time: d3, angularJS, node, flask, kinect.js, jQuery), I really appreciate “first contacts” that tell me in 10 seconds :

  • What is this thing?
  • Why would I care about this thing?
  • Is it worth the effort to learn this thing?

Source: http://stevelosh.com/blog/2013/09/teach-dont-tell/, which is a post “about writing technical documentation for programming languages and libraries.” Really, read it if you are at all interesting in having anyone else use your OSS project. After all,

The purpose of technical documentation is to take someone who has never seen your project, teach them to be an expert user of it, and support them once they become an expert.

okay, so what’s wrong with the internet today, you might ask?

chief complaints

1) Dumb websites that are 5% content and 95% whitespace.

2) Why do I have to clone, install dependencies, and compile my websites now? Whatever happened to good ol’ HTML view-source copy-pasting?

complaints in rant-worthy detail

1) Whitespace is good in moderation. Yes, don’t be afraid of whitespace. No, don’t waste my time scrolling down through empty galaxies of space. WTF. Hasn’t anyone heard of designing “above the fold“?

I’m not browsing for the latest python library to use on a tablet, I’m either on my laptop or my phone. What is this tablet interface thing? You can design for mobile / tablet without making your default website look butt-ugly on large monitors. I’m particularly ticked off right now because two of the projects I had bookmarked a month ago as being examples of “good homepage design” have converted into derp designs :/


december 2014

Source: https://www.djangosites.org/s/www-djangoproject-com/

february 2015

Screenshot from 2015-02-06 03:04:55

ugh, it’s like watching ubuntu upgrade into a progressively worse and worse UI-wise. (for the record, I use cinnamon and docky on Ubuntu 14.04 and I will fight to keep this working on my laptop). THERE’S SO MUCH USELESS WHITESPACE at the top left / right, ahhhhhhhh it’s infuriating to look at (I’m also really hungry, which is probably why I’m so grumpy right now)

As John Morris succinctly put it in Annoying Trends in Modern Web Design:

Minimalism is the practice of reducing fluff and streamlining websites.  When done correctly, this is very pleasing to the eye and makes finding what you want easy.  But when taken to far, your page becomes pointless.

good design

Screenshot from 2015-02-06 03:05:33

Whitespace? Yes. Mobile-friendly? Yep, checks out on my phone. Conveys necessary information in an efficient manner? Yep.

The other website is getfedora.org, but I can’t find a “before” screenshot for them, so I’ll spare them for now.

I started on this post a week or two ago, and I can’t quite remember the other points I was going to make, nor do I feel quite so angry (I think I was tired, sleepy, and hungry at the time of this post), but upon further reflection, I think the key issue I have with all these sites obviously designed for the tablet is that,

1) on the desktop, there is no easy “page” metaphor where you flip between one section to the next with a swipe of your finger.  If you’re going to treat tablet/mobile users as your first-class citizen, include navigation so that your site is intuitive on the desktop as well.

2) All the spaced-out, layered information (layered because you hid all the content under a metric ton of whitespace) (it’s clear people are designing for marketing: get them to click the button!) makes it very hard to build a mental map of your site. It’s like reading a book for ELDERLY PEOPLE WHO CAN’T SEE










unnecessarily so. There’s a reason why everyone doesn’t just use the EXTRA LARGE FONT setting on their computers or ebook readers. It’s uncomfortable, and I can’t build a mental / visual map of where all the information is. Take this site:


This site is well-designed for consuming information / first-time users exploring the site, but not for linking to content or commenting on it or remembering where things where on the site.





Getting started is up top, source code is to the right, news about the community over to the left.


Getting Started: Click the top button, then the link in the first sentence on that page.

Source Code: Scroll down about halfway on the page.

News: Scroll down all the way on the page.


stop copying other people’s designs willy-nilly to look cool without thinking about the usability of your site. =___=

Rarsday Robot: Laundry notification, part 0

I keep going down to the basement to pick up my laundry too early and chilling around in the freezing cold hoping if I just wait another 30 seconds it will finish.

Our laundry machine is free (whoo! no hunt for quarters!) but has no indication of how long it takes. I just hit “start” and come back in about an hour. This seems like a great fast project for Rarsday Robots. Sadly, I did not finish, but here is my rough concept.

1) photodiode masked so it only detects the “cycle complete” LED turning on/off (such a convenient setup!)

2) arduino plugged into the wall in the basement (yay no batteries)

3) either run wires up two flights to an LED (sketchy, even at 5v, also a lot of wire for people to trip on / for me to find at 1 am in the morning) or

4) some wireless communications. Bluetooth? Then it could ping smartphones. Is the BLE4.0 nrf8001 breakout we were using strong enough to go up two flights? Not sure. Also would need to develop smartphone app. Other possibility, use IOIO with regular bluetooth dongle (fast, only need to develop in one language). Or, use the cheap nrf24l01+ chips I have dozens lying around of!


Well, it took me 30 minutes just to find two working arduino nanos that I hadn’t desoldered the atmega328 from or otherwise destroyed, as well as remember that my `sudo apt-get install arduino` is sad (gives stk500 errors) and use a .tar.gz downloaded version of arduino instead. Oh well. Next Rarsday!

Next step: test whether Cappie’s nrf24l01+ code still works

Then test whether I get reception in the basement (set one to constantly emit something, see what I get out the other end on the 2nd floor. Ideally do this with someone else on the phone so I’m not constantly running up and down stairs).

The other part is to tweak around the photodiode / resistor (first, find one) until it works consistently, regardless of if the light is on or off in the basement or it is daylight or not (should be easy — just shield it well with tape). And put up a sign explaining what it does.

Finally, combine the two parts of the project. Voila, crappy laundry notification device. The second (receiving) arduino upstairs can do whatever, talk to your phone, the internet, or just blink an LED or LCD panel.

Further work: how to detect the dryer is done. Something that detects rumbling and runs it through a filter of some sort?x

Todo: buy more $3 arduino nanos

For your enjoyment: www.ruggedcircuits.com/10-ways-to-destroy-an-arduino/

How your “Team” pictures influence my desire to even apply

Lately it’s the “startup thing” to put pictures of your team up on your website. Now, I don’t speak for all female engineers, but as a female engineer who’s kind of sensitive about these things, fairly or not, it’s an immediate turnoff to see pictures like this

Screenshot from 2015-02-25 17:59:40

Screenshot from 2015-02-25 17:59:36

It goes roughly like this:

  • I open my email.
  • Someone forwarded me an email. “Cool drone startup that’s looking to hire!”
  • I click the link and read about it, then somewhere along the way I see a picture of the Team.
  • I get irked and leave.

Sure, you all could be a bunch of egalitarian feminist dudes, and if I just go work for companies with a lot of females already I’m exacerbating the problem in some ways, but really, just kind of a turn-off.

If you at all care about getting a more diverse team, here’s two simple solutions:

1) Just don’t post pictures of your all white-male founders / leadership / engineering team. No pictures are better, then I can’t form preconceptions (yes, I recognize the irony here) about your team. Also, the more people you have, the more I’ll look specifically for females in engineering leadership positions. Mixing in your female HR / support department does not help you.

2) Or, just put a simple statement to the effect that you’re aware that your team is very white and male and that you’re working on it.

That’s enough to let me know that you care, which is a big deal to me. Working in a place where no one cares about feminism or feminism is an awkward topic would make me bitter and unhappy (and I’d leave) within months. You’ll have to word your statement to overcome people’s jadedness (“yea, right, that’s probably just their HR talking.”) and show that your statement reflects your company culture.

Oh! Ladies, one thing I’ve discovered is that older guys are pretty alright. Something about marrying and having a family… My current co-workers are almost all older white males, but it’s in some ways a lot more comfortable than hanging out at MITERS, because feminism isn’t a dirty word or somehow less important than the latest in kilowatt lasers.

Today, I am a 41-year-old father and husband whose feelings on this issue have changed. I have come a long way since being a single, 26-year-old state senator, and I am not afraid to say that my position has evolved as my experiences have broadened, deepened and become more personal.

Congressman Tim Ryan

(Source: Rep. Dillon, Rep. Ryan)

p.s. This also goes for conferences… I’m looking at you, NERC.

nerc speakers

Wed: Visual Poetry, or “What’s in a Word?”

Wednesday Writing: Final Result

File: sheep-visualpoetry.svg (Inkscape SVG)

Simplified Chinese Text: 波士顿很冷, 可是朋友多, 可以包饺子,讨论有意识的想法。今年是羊年,感觉有一点老。最近心情好,每天有新的项目想踏上。希望你们可以给奶奶看这首诗,让她知道我想着她。主大家新年快乐,年年有鱼。爱,南西。

English Translation: Boston’s very cold, but there are many friends, we can make dumplings, discuss interesting ideas. It’s the year of the sheep, I feel a little old. Lately I’ve been in good spirits, every day I have new activities I want to embark on. I hope you can show grandma this poem, let her know that I am thinking of her. Wish everyone happy new years, every year with fish. * Love, Nancy.

* (err, it’s a play on “good fortune” and is a traditional new years saying)

Google Translate:

Boston was cold, but many friends, you can make dumplings, discuss conscious thoughts. This year is the Year of the Ram, I feel a little old. Recently a good mood every day want to embark on new projects. I hope you can see this poem to her grandmother, let her know that I think of her. Main everyone a Happy New Year, every year there is fish. Love, Nancy.

Yep, that’s a typo in my Chinese -___- I’m bad at this. Should be 祝, not 主, for 祝大家新年快乐. I’m not sure whether other issues are my bad Chinese or the bad translation by google 😛 Anyway, I did a quick fix.

OH NOT another typo, it should be想念她, not想着她. OH WELL. Chinglish it is.

Read up about it

Today I decided to investigate poetry which plays on our visual recognition of shapes.

George Herbert’s “Easter Wings”, printed in 1633. http://en.wikipedia.org/wiki/Concrete_poetry

I’ve seen some humorous Chinese ones passed around on the chat platform “wechat”, but can’t find them at the moment. Here’s the Traditional Chinese wikipedia page. Here’s the page on 宝塔诗 “Pagoda Poetry”, which seems restricted to triangles.


There is a similar poetry which plays on our auditory skills:


The following poem appeared recently in INFOCUS magazine. The original authors were Fred Bremmer and Steve Kroese of Calvin College & Seminary of Grand Rapids, MI.

The text of the poem follows:

<> !*”#
%*<> ~#4
The poem can only be appreciated by reading it aloud, to wit:

Waka waka bang splat tick tick hash,
Caret quote back-tick dollar dollar dash,
Bang splat equal at dollar under-score,
Percent splat waka waka tilde number four,
Ampersand bracket bracket dot dot slash,
Vertical-bar curly-bracket comma comma CRASH.

Try it out

Oh, I spent too much time looking around the internet to do a lengthy composition. Well, with thanks to velera3, here’s how to convert an text (poem) into the shape of an image in inkscape

My parents always complain I don’t keep in touch enough, so this will double as my diary.

1) find sweet sheep lineart: https://openclipart.org/detail/10543/chevre-by-yves_guillou-10543



2) put into inkscape

3) F1 -> select the goat -> Ctrl-Shift-F -> Fill = None, Stroke = Flat Color. Now it should be an outline.

4) Using the text tool (“t”), insert your poem into a text box

5) Hit F1, the select tool. Select both the text and the image. Text -> Put on Path.

(Note: Put on path –> the text curves along the lines of the image. vs Flow into frame –> the text remains in horizontal lines, but fits inside the shape of the image.

New document 1 - Inkscape_011
Hmm… not quite…

6) Do some manual editing. In this case, I chose only the main sheep body to flow my text onto, by duplicating (Ctrl-D) and deleting the other nodes. Then I made the stroke None and the fill White, used grouping (ctrl-G) so that the darn text and image would stop disassociating from each other, and voila.


Sparkyard: About

Published on: Feb 24, 2015 @ 7:12Edit

This site created by Nancy (orangenarwhals) in Feb 2015 order to have fun creating things. The focus is on quantity over quality: practice, practice, practice.

Monday Music A new piece of music, speech, or podcast every Monday. As flash fiction is to writing, so monday music is to music-making. or something.
Tuesday Terrible Startup Ideas A new terrible startup idea every Tuesday. From concept, to user interviews, to wireframes. An exercise in product design and idea iteration.
Wednesday Writings A new piece of writing every Wednesday. Flash fiction, poetry, generative text, ascii art, whatever involves text is suitable for Wednesdays.
Thursday Robots A new robot every Thursday. Loosely, any electromechanical object is suitable (no, twitterbots do not count).
Friday Fotovideos A new photograph or video every Friday. Street photography, tutorial videos, timelapse videos, those all belong to Fridays.
Saturday Scribbles A new scribble every Saturday. Whether it is webcomics (An Incoherent World), typography, propaganda posters for the Hexapod Revolution, or random scribblings, it belongs to Saturdays.
Sunday Silly Papers A new silly academic paper idea every Sunday. We show how everyone in the world, including people on the internet, can be a scientist by addressing the silly everyday questions with scientific rigor.


the visual language of crackpot websites (quick thought)

After visiting weatherishappening.com (boston’s most trust source 4 weather)

source: https://www.facebook.com/weatherishappening

and calling the hexagonal awareness hotline at 617.600.0606 “for immediate hexagonal assistance”,

source: http://hexnet.org/gallery

i developed this conspiracy theory that all crackpot websites shared the same visual language.

In general, a twisted visual style to match the twisted intellectual content. —timeblimp.com

Sadly my conspiracy theory has been dis-proven, which just goes to show how poor a crackpot I make 🙁

Thought: what do crackpot websites in other languages look like? Surely there must be crackpot Chinese physicists. do they make classical ugly websites along the lines of timecube.com? or is the more recent widespread internet usage in China than in US contribute to visual differences in crackpot websites there? What about Arabic or any other language?

Thought2: I should make a crackpot-CSS-styled website that actually gives very useful technical information, for instance serves up digikey datasheets.

Thought3: The complement to that is the take the trending-startup-webdesign or facebook design or hip bootstrap styles and make a slick looking website utterly filled with crackpottery. may encounter difficulty distinguishing it from your generic Industry Changing Startup website though. hmm.

anyway, you tell me which of the below websites are crackpot websites:

Screenshot from 2015-02-21 01:26:00 Screenshot from 2015-02-21 01:24:32 Screenshot from 2015-02-21 01:19:04 Screenshot from 2015-02-21 01:18:33 Screenshot from 2015-02-21 01:18:16 Screenshot from 2015-02-21 01:17:10

answer: all crackpots, probably, except weatherishappening (for sure) and hexnet (probably, he seems like a pretty chill dude. he showed up at hexacon2013.mit.edu, and really, if we don’t judge people who collect stamps (they even have a name, philatelics), why should we judge people who collect hexagons?)

And to close, here’s a gem of a crackpot:


NB: You can read this essay as science fiction or science fact. It’s up to you.

First Some Theory

One of the most elegant forms of ZPE devices is the Dirac Current Positron Generator. Once you can finesse the low energy generation of positrons from the quantum vacuum, letting nature supply the bulk of the energy requirement for the task, you then can release large amounts of usable “free energy” by simply letting the positrons annihilate with electrons under controlled conditions. …

What is nifty about our process, though, is that we can “freeze” the sc condensate into a permanent steady state much like the frozen positrons that are stuck inside the protons or like concubines sequestered in a harem. The sexless quark eunuchs insulate the sexy positrons so the poor horny bachelor electrons nearby just can’t get in close enough to mate with them and go out in the orgasmic glory they desire. So the charged up electrons do the next best thing and go into “mental” fantasies and complex ritual patterns. That generates EM fluxes and molecular structures that weave a complex web around the protons. A kind of “civilization” emerges with a wonderful variety of long-lasting sublimation rites.

wat. what did i just read.


yours truly in wasting time on crackpot websites,
~ orangenarwhals


thanks to the original reviewer / theorist of just how crackpotty these crackpot websites are, http://timeblimp.com/?page_id=286

The TimeBlimp Universal Theory of Crackpot Websites:

1. Horrendous grammar, spelling, and general use of language

2. Declaration that some pillar of science is completely wrong

3. Unprofessional, irritated, emotional tone to the explanations.

4. They usually have websites (what better way to publish to the masses), and their websites are almost always one gigantic continuous long stream of text and figures in one page. The site design is awful, with clashing colors, abuse of blinking text, terrible font sizes and colors. Oh, and they often use ALL CAPS TO EMPHASIZE POINTS, and embellish important sentences with lots of exclamation points!!!! In general, a twisted visual style to match the twisted intellectual content.

5. Invention of their own definitions

Head over to timeblimp.com to read in-depth reviews of each crackpot website, as well as the reveal of the winning crackpottiest crackpot website!

National Weather Service fun facts

if I have been blogging a lot, it is because I redirected facebook to localhost on my computer via /etc/hosts, so here we go

1) THEY TYPE IN ALL CAPS…EVEN THOUGHT IT IS 2014… Their forecasts are often broadcast on radio for seafolks or airfolks using voice synthesizers. The ellipses are equivalent to a comma, but in the super early days they only had periods and ALL CAPS. The NWS keeps it this way to comply with global standards which include countries with old equipment. Their are proposals to adopt crazy new features like mixed caps and more punctuation signs.

2) There are three voices since 2002, two male and one female voices (and a male Spanish voice). You can listen to the here: http://www.nws.noaa.gov/nwr/info/newvoice.html

3) Metereologists have a sense of humor, and that’s sometimes sprinkled into the official forecasts, like below:

(from: http://xkcd.com/1126/)

(I have two examples from this year’s Boston snow craziness here: http://www.orangenarwhals.com/?p=1593)

conveying complex technical information (quick thought)

there’s something that interests me, but only because I encounter it done poorly everywhere and it REALLY IRKS ME.

I’d much rather it be someone else’s problem, but in lieu of that I often find myself ranting about it or fixing it myself as best as I can.

It’s something like “conveying complex technical information”. In fact there are professional “technical communicators”, but their conferences are just case studies of things done right and wrong (and the way the people describe themselves :/ seems not exciting to me).

I would define my interest in this way:

Conveying complex technical information

Transmit success rate:
100% = telepaths
0% = speak/feel different languages and are blind

Specific applications:

  • Education: university STEM students, high school students. Blank-slate brains to fill with information!
  • Academia: why is this paper so hard to read? why does it take new PhD students 12 months to understand the state of the field?
  • Data sciences: i need to find insights in terabytes of data. help.
  • Engineering projects: why does it take so long to figure out whether to use this tool or that framework?

It touches on

  • document design / website design
  • visualizations
  • how to write well
  • interface design (make good GUIs)


  • Goal: increase success rate & decrease transmission time
  • docs (sphynx, liquify, doxygen, readthedocs, jenkyll)
  • screenshots or video (shutter, gtk-recordmydesktop, gfycat)
  • visualization tools (d3.js, ipython, R)
  • software replacements for editors (checks to see if your paragraphs are structured well, flow coherently, etc.)
  • tools to map your mental models

Transmission fails if:

  • person loses interest
  • person receives all information but models information incorrectly, or
  • loses information because it falls outside their model

Ideally, the transmission

  • Delights and inspires
  • Encourages thinking
  • Encourages new ideas / connections to be formed

Okay, if I think anymore about this topic my brain will explode. Time to go to sleep.

Do you trust the police? (my response to Patel)



The tragic story of Sureshbhai Patel‘s arrest and serious injury (partial paralysis) 1.5 weeks ago (on Feb 6th, 2014) resonates strongly with me for a few reasons, despite the fact that I am not Indian.

I am not here to discuss police brutality or white privilege or any of another alienating terms that people “know their opinion on.” I am here to discuss my personal feelings and experiences.

Here is the dashcam video of Patel’s arrest and injury, should you wish to judge for yourself.



Patel is 57, around the age of my parents. I love my parents a lot. Although 60 years old seemed crazy old to me a few years ago (when I was a teenager), my parents are in good health and kick my butt in getting stuff done, including physical chores.

grandparents leaning in


I am friends with a Chinese couple (the husband works in biotech and the wife is a Harvard grad student) in my area. They recently had a baby, and their parents flew in from China to help take care of the baby. (I’m not sure if this is a thing in European cultures? but I think it is common in Chinese cultures for the grandparents to take care of the children while the parents works. See here and here). So immigrants bring this cultural mindset with them.

(By contrast, I’m an ABC, in other words I was born and grew up in the US, and find the thought of my parents taking care of my baby to be weird and unrealistic… Actually, I’ve instilled in myself a deep suspicion of babies, so the words “my baby” :s eww).

Like Patel,  my friends’ parents speak almost no English, but are by no means stupid. They (the grandparents) constantly invite me over for dinner and cook delicious foodstuffs for me, oh man, now I’m hungry. Sadly I can’t find any pictures of the food they cooked right now (possibly I don’t have any pictures). They always send me home with tupperwares of leftovers too. As a result, I’m quite fond of them, even if making conversation is a bit of a struggle due to language, cultural, and generational differences.

English as a Second Language

I’ve known from a friend’s experiences that simply not knowing English or not understanding it well enough / fast enough can get you arrested, even if you’ve spent decades in the US, worked your way up from being a dirt-poor immigrant, and now contribute to the US economy, pay your taxes, and are generally an upstanding citizen.

To get your record cleaned of an arrest when you did nothing wrong is still an easy few thousand dollars in lawyer’s fees. They did not benefit from police cams; they swept their arrest under the rug out of shame. Shame for what? Not being born in the US? Years later, it’s just something to be bitter about and not ever bring up again after dealing with it.

As a result, since a young age I’ve been open to the idea that our justice and policing system is not perfect.

Do I trust the police?  Unfortunately, instinctively I do not.

due to my aforementioned experiences.

I temper my gut feelings with the knowledge that I should look more into the research behind whether police are trust-worthy, since my personal experiences will only ever constitute a part of the whole picture.

global comparison

For instance, having visited other countries, I am able to get some prospective and understand that the US is pretty high up there in terms of standards of governance. In 2008, the US ranked in the 90-100th percentile in terms of perceived corruption:


Or from the world bank in 2013, with links to the methodology:

Interactive version: http://info.worldbank.org/governance/wgi/index.aspx#reports

Personally, I’ve visited several other countries where, in broad daylight, police officers will deliberately lead you (tourist in car = people with money) astray or ambush you, waste your time and make you sweat, and then threaten you with a ticket unless you realize what is going on and pay them a bribe.


None of these facts excuse us from working together to build more just and trustworthy social systems. Our rule of law in the US maybe be good, on average, compared to the rest of the world. But you or I could easily be caught in one of the “outlier events” and lose thousands of dollars, our mobility, or our life. Averages are small comfort then.

Thanks for listening.