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)

Tools

  • 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)

 

patel
http://www.gofundme.com/m757pw

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.

fifty-seven

 

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:

http://en.wikipedia.org/wiki/Worldwide_Governance_Indicators
http://en.wikipedia.org/wiki/Worldwide_Governance_Indicators

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

http://info.worldbank.org/governance/wgi/index.aspx#reports
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.

However,

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.

Cinnamon 2.4.5 & Ubuntu 14.04: stop it from crashing & battery notification fixes (xmobar, cronjob, notify-send), fix pidgin

Cinnamon is a “desktop manager” that is visually similar to Gnome 2 while incorporating new features from Gnome 3. It does not have an official Ubuntu package.

key features

these are the reasons why I don’t use whatever came with Ubuntu 14.04 and sink time into my own setup

  • Edge Tiling and Snapping: I can drag a window to the sides tile it, or use Win-[arrowkeys]
  • Workspaces and hot corners: Allow me to add more workspaces, title them. Using cinnamon-settings, I put my hotcorner in the bottom right
  • Switching windows: If I have a lot open, “Expo view” lets me see open windows quickly (ctrl-alt-down)
  • Built-in panel applications: Supports the normal stuff (tomboy notes, pidgin, volume, notifications) as well as custom applications (pomodoro timer, timer). Cinnamon panel has its own “app store”-like interface (I don’t show it here) where you can add other people’s applications painlessly
  • Top panel (cinnamon panel): Shows me which windows are open in my current workspace
  • Big frequently-used icons: Using docky, I put my most frequently used applications to the left side and can easily see how many instances of each application I have open across all my workspaces
  • Search across applications: Similar to Windows 7, I can type in a keyword and Cinnamon Start Menu will pull up the appropriate program, so I don’t have to hunt for the command-line name for infrequently used programs

stop crashing

A few days ago, I accidentally updated my cinnamon install. I thereby spent the next half-day hating myself.

I had been using the nightly package from Gwendal Le Bihan. Upon closer inspection, that repo was discontinued. I tried to follow  http://www.omgubuntu.co.uk/2014/07/new-cinnamon-ubuntu-14-04-ppa-stable to upgrade my Cinnamon to a newer version, but cinnamon still flat-out refused to start (“Cinnamon crashed, would you like to restart Cinnamon?”).

Eventually, I installed Gnome 3 in a fit of trying out desktop environments that would be “good enough.”

$ sudo apt-get install gnome-session

When I rebooted, I no longer had any gnome options to select from, although the “user login” screen had definitely turned into some gnome 3 thing. But I could select cinnamon and it no longer crashed!

what. -___- Oh, the woes of linux customizations.

pros/cons

Upgrading did fix things. I no longer get lots of “Ubuntu detected an error in your system” pop-ups when I reboot. Tomboy appears in the panel again (yay!! I really like Tomboy). There is a “hotcorners” GUI editor now. Oh, and I have pidgin tray icon, except I have manually toggle it on and off for it show up instead of a blank space 🙁 (see https://bugs.launchpad.net/linuxmint/+bug/1325103)

EDIT: I fixed pidgin system tray notifications! Cinnamon > Panel Settings > Check “Use customized panel size”  & “Allow scale icons”. My top panel is set at the default font size.

If that doesn’t work for you, try this: https://pidgin.im/pipermail/support/2013-January/026238.html. I can confirm that editing the icons in “/usr/share/pixmaps/pidgin/tray/hicolor/16×16/status” changes the icons in cinnamon’s status bar.

Sadly, restarting is still slower than it should be, and feels even slower now. I swear when I first installed the SSD my boot-time was at least 5 seconds faster, which may not sound like much, but makes rebooting feel a lot less painful (for instance, when switching between Windows and Ubuntu, because **** xbees and their windows-only gargantun XCTU, that’s why)

My wifi will suddenly die for no reason, and I have to

$ sudo restart network-manager

Cinnamon itself will freeze sometimes, I haven’t figured out why. Then I have to Ctrl-Alt-F1, log-in, and run

$ sudo killall Xorg

My suspend still doesn’t work, so I just shut-down the computer (the fan is loud and I have perhaps forty minutes of battery life).

Shutting down takes on the order of a minute :/ I want to leave already. Also, my zombie computer’s fan keeps going & hard-drive monitor LED keeps going for several seconds after my screen blanks out on shutdown… :/

Worst of all, power management no longer worked. Not only did the battery indicator not update, my laptop would just instantly die with no warning when it ran out of battery.

This is because Cinnamon switched how it checked battery status: https://bugs.archlinux.org/task/39989

This looked promising, but I could not get anything to show up in my Cinnamon panel bar: https://github.com/robin92/cinnamon-power-applet

version info

$ cinnamon --version
Cinnamon 2.4.5
$ lsb_release -a
Ubuntu 14.04.1 LTS
$ gnome-session --version
3.12.1
$ docky
Docky version: 2.2.0 Release

create battery status indicator

This was straight-forward-ish. I used another program entirely,  xmobar.

$ sudo apt-get install xmobar

Cinnamon does not respect keeping xmobar on top (windows will cover xmobar), so I just stuck it behind my semi-transparent Docky (Theme: HUD), since Cinnamon never tries to cover up docky. Hence, the “fixed-width bottom left” position. I increased the font-size (to 20).

full battery
full battery. 100% = percent remaining, f = fully charged
xmobar-charging
charging
xmobar-notcharging
discharging

Then there’s a mess of battery commands — basically, defining the colors when high, normal, or low battery, defining the thresholds (% remaining) for high, normal, or low battery, and then defining the “acstatus” (charging/discharging status) characters — I chose “-!” to indicate discharging, “f” to indicate full battery, and “+” to indicate charging (xmobar does not support fancy unicode arrows by default).

The template goes “battery percent left” and then “acstatus”.

$ cat ~/.xmobarrc 
Config { font = "-*-Fixed-Bold-R-Normal-*-20-*-*-*-*-*-*-*"
, position = BottomW L 3
, bgColor = "black"
, fgColor = "#f3f3f3"
, commands = [ 
 Run Battery ["-t", "<left><acstatus>"
 , "-L","49","-H","75","--high","green","--normal","yellow","--low","red"
 , "--", "-o", "-!", "-O", "+", "-i", "f"
 , "-f", "ADP1/online" ] 20
]
, sepChar = "%"
, alignSep = "}{"
, template = "%battery% "
}

The last “template” line just adds a “space” after the battery template is rendered.

Oh, about the -f option, that’s another possibly ubuntu-specific or laptop specific thing…

https://code.google.com/p/xmobar/issues/detail?id=36

Q: In the git version of src/Plugins/Monitors/Batt.hs , in the haveAc function, we try to find out whether the computer is on AC power by checking “/sys/class/power_supply/AC/online” . On some computers this is instead located in “/sys/class/power_supply/ADP1/online”.

A: i’ve added a new config argument (-f) to specify the online file.

While you’re setting this up, you can use

upower -d

to check your battery state manually.

Finally, add xmobar to startup: Ubuntu comes with “startup application preferences” GUI. Click “Add” and put in command “xmobar”. Done!

create low battery warning

example notify-send notification
example notify-send notification

Thanks to http://unix.stackexchange.com/a/60936/14574. Essentially, I use notify-send to pop-up a low-battery notification using a shell script that I run every 5 minutes using a cron job.

It turns out cron hates notify-send so this ate up way too much time.

(I think crontab -e does persist across reboots by default, fortunately). I followed several guides, I’m not sure what exactly fixed it in the end, but here is my full setup for running the checker every 5 minutes:

$ crontab -e

*/5 * * * * sh /home/nrw/.notify-send_setup
*/5 * * * * sh /home/nrw/.battnotif

$ cat .notify-send_setup

#!/bin/bash
touch $HOME/.dbus/Xdbus
chmod 600 $HOME/.dbus/Xdbus
env | grep DBUS_SESSION_BUS_ADDRESS > $HOME/.dbus/Xdbus
echo 'export DBUS_SESSION_BUS_ADDRESS' >> $HOME/.dbus/Xdbus

exit 0

$ cat .battnotif

#!/bin/bash
export DISPLAY=:0
XAUTHORITY=/home/nrw/.Xauthority

if [ -r "$HOME/.dbus/Xdbus" ]; then
    . "$HOME/.dbus/Xdbus"
fi

battery_level=`acpi -b | grep -P -o '[0-9]+(?=%)'`

# I tried to only notify when not charging, but could not get it to work
# STATUS=$(cat /sys/class/power_supply/ADP1/online)
# if [ $battery_level -le 15 ] && [ $STATUS == "0" ]

if [ $battery_level -le 15 ]
then
    /usr/bin/notify-send -u critical "Battery low" "Battery level is ${battery_level}%!"
    echo 'batt low' >> /home/nrw/cron.log
fi

echo 'ran batt' >> /home/nrw/cron.log

Make sure to chmod +x the bash scripts.

projects blog (nouyang)