Filter

What To Write About?

After two months of not writing for Just a Gwai Lo, I still haven't come up with anything important (urgent!) to write about. Quality control needs improving, and the best idea I could come up with was to hire an editor. Which would mean, in essence, paying someone to tell me what to write about.

(How many blogs are edited in the traditional sense? With assignments, deadlines, correction, feedback, rejection? Has the nature of editing and roles of editors changed because of blogging? Are individual editors relevant anymore that we "crowdsource" the process?)

While on 'hiatus' here, I've written about floorball and other topics at Urban Vancouver, and kept posting to improvident lackwit (Heckhole, Lord Palmerston, Crazy Town, and today, Tiananmen Square). I thought about news that matters to me: it needs to be local, match my interests without perpetuating tunnel vision, be "actionable" and allow me to "add value" to it, among the other features listed in Dave Pollard's piece on continuous environmental scan. I successfully pursued outdoor exploits, regained if not my figure then at least a better outlook about it, created about the same, which is to say not a whole lot, moved from del.icio.us to Ma.gnolia, kept up with Twitter, Vox, NowPublic and Flickr but gave up on Facebook, at least for the moment.

Sharing still doesn't feel as meaningful as creating, though. So what's a person who doesn't feel very creative to do? At least be grateful that the flow of work email shows no signs of letting up?

TextMate Hallowe'en Easter Egg

Scary TextMate Dock Icon

After saying yes to the TextMate update dialog box, the icon changed into a scary jack-o-lantern (seen left) and a window with a spider web. I don't use text editors that much (most of my scripting and text editing happens in a console window), but for notes and modifying existing plain text, it was worth the purchase price. I also love the screencasts, which clue me into some features that make repetitive tasks easier, the most useful so far being the screencast introducing how to use TextMate in conjuction with HTML tags. A day early, at least here in the Pacific time zone, for the easter egg, but still fun.

(Not technically an easter egg, since you usually have to do something for them to happen. But it's the best approximation of what this is.)

And yes, even though I don't really celebrate it—too loud and scary—I still spell the cultural holiday celebrating death with an apostrophe.

Notes on "Documentation in the Open Source World" at the Free Software and Open Source Symposium

My worries about Eric Shepherd's presentation being too focused on developer documentation were both correct and unfounded. Correct because he only talked about developer documentation for the Mozilla Corporation. Unfounded because everything he talked about applied directly to end-user documentation writing. Some notes here, then a paraphrase of my comment-slash-question at the end. He broke the talk into sections:

  • planning and organizing
  • the five C's of documentation
  • creating documentation
  • who decides who writes
  • gathering information
  • some do's and don'ts

He showed a continuum of openness, from less to more open: published documentation (without comments), commented documentation, and collaborative. The distribution of documentation also proceeding on a continuum from less to more distributable: printed, downloadable, and browseable. He also talked about the advantages of using wikis—anybody can contribute and correct, they take advantage of everybody's strengths, and even non-technical people can contribute—and their disadvantages (prone to sabotage, clueless-if-well-meaning people, and potential for spaghetti documentation. Mmm, spaghetti documentation.

The five C's of documentation that Eric listed are:

  • completeness, meaning cover all topics and make the documentation as thorough as possible, but not too thorough.
  • correctness, with testing of sample code (or, in my case, the instructions I write out for people)
  • clarity, meaning formatting and writing in easy-to-understand language designed for readability.
  • convenience, meaning organize the documentation so that the solution is easy to find.
  • consistency in language, spelling, grammer, colours and formatting

Creating documentation means making tough choices, depending on the time a writer has to write the documentation but also how soon to revisit. He recommended finding ways to remember and remind to revisit documentation as new releases of software come out. As to who writes the documentation, since he discussed developer-focussed documentation, he listed developers, writers, managers and readers. No mention—at least to my recollection—about users, but maybe readers encompasses that groups. He touched on documentation requiring maintenance (everything requires maintenance) by monitoring changes both in the software and the documentation itself and monitor its organization. Also he listed some tools (wiki discussion pages, IRC, email and instant messaging) used to communicate between programmers and documentation writers, and, by extension, users.

An interesting section of the presentation focused on information gathering. He listed reading design notes, discussion archives, source code and asking the programmers themselves, but I wondered about casting the net wider, like asking the community as well as the users. I sometimes come across something that I know—or think—is possible and want to document, and I know if I ask on the support forums I'll get an answer, but as a documentation writer, I'm afraid of looking like it's something I should already know. It's something to get over, since at the end of the presentation he gave some advice to documentation writers which included "check your ego at the door" and "don't be territorial" and "collaborating means admitting that someone knows more than you." That last one is the answer to my worries, and I'm going to make an effort to ask the community if something is possible and how, and if appropriate or necessary, elaborate on the answer in a step-by-step way.

Notes on "Documentation: A Key to Openness" at the Free and Open Source Symposium

At the Free and Open Source Software Symposium at Seneca College at York University (not the Markham campus, to my embarrasment), I came in late to the documentation and openness presentation and took some brief notes. Presenter Chris Tyler recommended breaking documentation tasks into beats, which I interpreted to mean have leaders/managers/editors assign documentation tasks, push them just hard enough to write quality and up-to-date documentation, and not assume that "the community" will automatically contribute. (Near the end of the presentation he wondered why many open source projects have, as their suggestion for users' first contribution to the project, writing documentation if they are possibly the least familiar with the product. It might be that I misinterpreted this, but there is some value in encouraging those who are—or, even better, were—frustrated with a portion of the software to voice their frustration at the quality of documentation and submit their own so that others might come in and edit and, if necessary, bring the documentation up to the standards of the project.) He had a favourable opinion of projects like MySQL (or, the example I would have used, PHP.net) as documentation websites allowed for comments where people can comment with their alternate solution or a correction that might later be incorporated into the official text. He also liked the idea of people writing HOWTOs on their own weblogs. He complained about the unidirectional nature of links in the current version of the Web (2.0 if you didn't already know), but documentation with comments open would permit dropping a link in the official documentation's page, making it a "manual trackback" of sorts.

In the discussion, someone mentioned that there's a balance between professional quality and community input. As well, someone mentioned the desire for a balance between community involvement and appropriate length of documentation (especially true of wiki pages, but also applies to documentation with comments enabled), as individual pages may become unwieldy over time. Video documentation (the word screencast wasn't mentioned, but many software packages defy easy written description but can be shown in a few minutes or even seconds). The other problem Chris mentioned about documentation —other than asking users to contribute help texts when they may not be familiar with the product, addressed above—was translation of documentation and keeping the translations synced up, especially with documentation in wiki format. A few times the people in the room mentioned the need for new tools but a lot of the problems sound like they can be solved better socially or organizationally.

Naturally metadata made its way into the discussion, and more than 2 people were frustrated with the way the Google search engine is setup for people to find documentation. I don't share their frustration, nor do I share the frustration with the seeming lack of authority of documentation found on sites other than the project's official website, because for the vast majority of problems I needed solved I've found through a basic search engine. Granted that much documentation needs to be 'tagged' for the version that it describes, but the tools for doing that exist: it's a matter of "just" doing it.

Some things not addressed by the presentation, at least not while I was there was documentation hosted services based on open source software? While I'll be the first one to admit that <ahref="http://support.bryght.com/">Bryght's support documentation is not always complete (that's what the support forums are for, so that people can ask questions and then we can update the documentation with our answer) nor is it always up to date (mea culpa), Bryght has a larger degree of control over what version of the software running there than a downloadable product, since Bryght does all the updates for everybody. I'd also be interested in how companies contribute their documentation back to the communities from which they run their hosted services (or even from where they get the software they host a possibly modified version of for download). People are free to use Bryght's documentation for their purposes since it's licensed under the Creative Commons, though there's no automated way other than screen scraping or copy & pasting to migrate documentation from one place (support.bryght.com) to another.

Next up, in a few minutes, is Eric Shepherd's presentation on documentation in the open source world. From the looks of the summary, it looks to be about developer documentation, not end-user documentation, which I think is more interesting if we're to help sell people on open source.

Free and Open Source Documentation at FSOSS: Introduction

Those following my Upcoming.org stream know I'm currently in Toronto (after a vacation in Iceland!). I'm attending Day 2 of the Free and Open Source Symposium, with specific interest in Chris Tyler's presentation on documentation and openness and Eric Shepherd's presentation on documentation in the open source world presentation. Documentation in open source is a bit of a long-standing issue, since many open source tools have the impression that they were built for developers. At Bryght, I've written a lot of the support documentation for the Drupal-powered hosted service, and without formal training in documentation-writing, I'm hoping for some more eye-opening on the subject. I don't have any Bryght swag to give out other than my business card, but you can meet two of the Bryght guys (James Walker is also there, presenting on the violently awesome Drupal).

(Re-)Documenting My World With Drupal and the Nokia N95

After I tell two people an idea, it probably makes sense to publish it somewhere so that someone can go out and implement it. Here are the ingredients:

  • a site powered by Drupal 4.7
  • Location module for Drupal
  • GeoRSS module for Drupal
  • Aggregator2 module, though its successors are currently in heavy development
  • A . Or any mobile device that combines GPRS, GPS, and a camera and a phone. The phone part is completely unnecessary, but that conveniently limits us to the Nokia N95.
  • (optional) Google Maps and Views modules for Drupal

I say optional for the last one because you would only 'need' it to display a map on your own site. (Which I do: more on that later.) Some assumptions, using Vancouver as my example. Since we all have a natural urge to let complete strangers know not only that there's nobody back at home but also to let those same complete strangers where we are at all times, say I'm walking in Stanley Park and want to make a 'live' document, with a map, of the walk I'm taking. With photos and video, say. Say, also, that I have a reasonably-priced unlimited data plan, the same reasonably-priced unlimited data plan I moan and groan about not having. Here's what would happen:

  • I would take a photo and automatically upload it to Flickr, the GPS taking care of the co-ordinates and geo-tagging as I walk around.
  • Flickr then displays it on its map. That's really neat, but not the exciting part. In the RSS feed, Flickr adds the longitude and latitude to each photo's item.
  • My Drupal-powered site takes in the RSS feed, and thanks to the Aggregator2 module + the Location module + the GeoRSS module, automatically adds the longitude and latitude to the individual item.
  • I map it on my site using the Google Maps module. That's really neat too, but still not the exciting part.
  • The GeoRSS module also adds longitude and latitude to my site's RSS feed.

That way someone could come along and use my liberal "Attribution" (no other restrictions) Creative Commons License and do something with it. Add it to a mapping aggregator (like mapufacture that displays crimes committed in Stanley Park, which would be so nuanced as to point out where crimes didn't happen. So hopefully, assuming the current odds of my being involved in a crime at any given moment, it will map out that data point at that particular moment.

We now come ever closer to having all the tools we need to not only document our environment, but to let others re-document it in different, unimagined ways. Right now the process is fairly time-consuming: before even knowing about GeoRSS, through a process involving manually looking at Google Maps of the area, then parsing out the Google Maps URLs for coordinates, I pasted in longitude and latitude for each station so far on my SkyTrain Explorer walks. That gets me a cute map of each walk (clicking on the label goes to the walk's individual page), and thanks to the SkyTrain walk feed (generated with the Views module) that contains geographical data (courtesy the GeoRSS module) you can get the points plotted on an external map. Which also happens to use Google Maps, but the point is that the service, through a standard to output location data in RSS and a few other pieces, someone else can use an external service or pull down my RSS feed and do something with my location data.

By few, of course, I mean "a lot of", since none of it comes out of the box, as you need to glue together a content management system, modules, and a little bit of manual labour. The Nokia N95 takes care of the manual labour part, and the wifi modem makes grumbling about lack of a GPRS plan almost pointless. (Almost.) It also takes out of the hard work of learning mapping, mobile devices, location-aware tools—and increasing my own location-awareness—as I try them out, since they'd all happen at once. And it would be fun!

I'm not worried that some evil-doer has, after reading the above, gained knowledge to hasten our doom. I'm 100% confident they would have figured that out for themselves.

Canucks on HNIC

The website for the CBC, Canada's government-funded TV network that takes ad revenue and has as one of its most popular shows an American cartoon, has a list of all the games that they will show as part of Hockey Night in Canada. HNIC is, historically, all of Saturday night during the fall and winter as well as spring during the playoffs, though sometimes—especially the playoffs—those days are weekdays and/or Sundays. The listing they show isn't very useful, I found, since they show the times in Eastern and there's no obvious way to quickly switch to Pacific, the time zone I currently reside in. Also, it's not clear to me which team is the home team. (I guessed, correctly, that it was the team on the right.) Also, it's not in calendar format.

So, mostly to experiment with Drupal's features (Event + Location + Views), I created a calendar of all the Vancouver Canucks games shown on the CBC. I even created an iCal feed (which doesn't really work...). Why only Canucks games? Because that's the team I cheer for. Why games only on the CBC? Because that's the only channel showing hockey games that's not on TV that requires me to pay money. I could, though, add the games that are pay-per-view and on other networks, since I do occasionally go to a buddy's house and watch those games.

(If there are any errors in the calendar, let me know and I can make the change.)

Yes, yet another Drupal-powered site, which you can sign up for and write a weblog for if you like. I plan on writing there not very often, not really knowing what I'm talking about, but I'd like it to be an aggregation point for everything that people—bloggers and others—are writing with regards to my longtime-favourite hockey team.

Les problèmes se font jour

Karl: Une communauté jeune est relativement stable, homogène, pleine d'enthousiasme. Tous ces éléments permettent son succès. Ceci est valable pour pratiquement toutes les communautés. Et puis lorsque la communauté s'élargit en nombre de participants, lorsque la technologie est utilisée à large échelle, les problèmes se font jour. Ils sont souvent de même nature que ceux que l'on pensait résoudre.

Nokia N80: An Initial Review

A forwarded email and a phone call later, I'm the owner—or rather lendee for about a week—of a Nokia N80. Since June when I lost my 7610 in Seattle, I've been using the Nokia N70, which has a really great camera for both stills and video, and a soft, friendly keypad. (I do a lot of text messaging these days.) Initial impressions of the N80 are:

  • the keypad is nice, and the slider protects from accidental phone calls (the phone, when sliding closed, asks whether to lock the keypad), but I'm used to the layout feel of the N70, so I don't like the N80's as much
  • S60 3rd edition looks nicer than 2nd edition, which runs on my N70
  • the ringtones—I only have two, both of which are MP3s: Aaliyah's "(Outro) Came to Give Love" and Cut Copy's "Future"—sound great, possibly better than my N70, but that may just be the honeymoon one grants when using a new product
  • the blue blinking light is annoying when the phone is sitting next to my computer, acting almost like a beacon, reminding me that the phone is still there
  • the photos I've taken with the N80 so far aren't as good as I thought they'd be with a 3 megapixel camera, but I like the camera button when holding the phone in "landscape", and maybe I just need to fiddle with some settings

The wifi is pretty neat, as I spent about an hour surfing around while laying in bed, using Opera Mini which this site looks okay in, but the mobile version looks just about right in. Wifi on my phone is pointless other than to upload photos using Shozu, since if I'm at a place that has wifi I probably already have my laptop with me. The ease with which I can upload photos and, potentially, stream live video makes me wish for an inexpensive unlimited mobile data plan even more.

See also: a long review by Zack Smith of the N80 with photos of the phone and photos taken by the phone; who should and shouldn't get an N80.

The Lifebox, The Seashell, and the Soul by Rudy Rucker: Chapter 2: Our Rich World

Rudy Rucker explains three world-views of physics in the second chapter of The Lifebox, The Seashell, And the Soul: the mathematical physics view, the continuous cellular automaton view, and the particle system view. I sorted the three from the view I most understand which is what they taught me in high school to the view I least understood, the view they tried to teach me in university, which forever soured me on the subject. (As for celular automata, they didn't even try to teach us that in school!) The ramp from discussing cellular automata in the book is pretty steep, so I could probably use a book-length treatment of the subject with a nice, gradual incline.

Earlier in the chapter, Rucker defines analog and digital not in terms of absoultes, but in terms of the size of discrete possibilities. His definitions I find satisfying, adding nuance to the definitions of them I had in my head, wihch were something along the line of digital == ones and zeros and analog == fuzzy values. Another satisfying definition—or rather, illustration—comes when he discusses chaos and the effects of small differences from experiment to experiment lead us to conclude that we have to think in terms of averages and probabilities and not absolute laws when predicting events in our physical world. But just as the honours physics class I mistakenly took at SFU lost me with quantum physics, so does Rucker, with photos behaving as a wave and particle based on how one observes the behavior.

The discussion then turns to theories of reality, and Rucker seems to be arguing that time (such a "past" and "future") are an illusion—lunchtime, said Ford Prefect, doubly so. Cause and effect don't so much not exist but rather causes and effects send messages to each other forward and backward through time. This theory, if I'm summarizing it accurately, doesn't get Rucker into the Wikipedia page on the philosophy of space and time, but at least it gives people like me who need an excuse not to attend a meeting in the future by saying we are living in an 'eternal now'. Or something: the argument relies heavily on the scenario presented on pages 138-139 which don't make a lick of sense to this political science major.

Pages