May 31 2007

Videos Introducing Wiki and RSS

Common Craft explains wikis and RSS quickly and clearly, with panache.

Wikis in Plain English:

RSS in Plain English:


May 17 2007

Configuring Pidgin for Google Apps

Google’s instructions for configuring Pidgin with Google Talk have a broken link to instructions for using Google Apps with a corporate domain.

So here’s how I configured Pidgin to work with a corporate Google Apps account:

1. Select “Add/Edit” from the Accounts menu, then press the “Add” button.

2. Fill in fields on the basic tab.

  • Protocol: XMPP
  • Screen name: johndoe
  • Server: example.com
  • Resource: Home
  • Password: ********
  • Local alias: John

3. Fill in fields on the advanced tab.

  • [x] Force old (port 5223) SSL
  • [ ] Allow plaintext over unencrypted streams
  • Connect port: 5223
  • Connect server: talk.google.com
  • Proxy type: Use GNOME Proxy Settings

4. Press “Save”. Don’t “Register”, because your username should already be assigned.


May 17 2007

Pidgin on Ubuntu 6.10 (Edgy Eft)

Pidgin 2.0 (formerly known as Gaim) has been out for a couple weeks now, and I wanted to try it out. I haven’t upgraded to the latest Ubuntu yet, so the normal convenient installation procedures do not apply. There’s probably an apt repository or deb file somewhere, but I couldn’t find it. So it was time to compile from source. This was made a little more complicated because I wanted to use Pidgin with Google Talk (aka GTalk), which requires SSL support.

Here are the steps that I took to build and install Pidgin on Ubuntu 6.10 (aka Edgy Eft). Maybe it will save time for somebody else in a similar situation.

Disclaimers: Your mileage may vary, since I might have some prerequisites already installed that you do not. There might be an easier way to do this, and I stopped optimizing as soon as I got something that worked for me.

1. Get the source bundle from the Pidgin download site

http://pidgin.im/pidgin/download/source/

2. Extract the contents

tar jxf pidgin-2.0.0.tar.bz2cd pidgin-2.0.0

3. Install some prerequisites

sudo apt-get install \
     libglib1.2-dev \
     libglib2.0-dev \
     libgtk2.0-dev

sudo apt-get install \
     libnspr-dev \
     libnspr4 \
     libnspr4-0d \
     libnss3 \
     libnss3-0d \
     libnss-db \
     libnss-dev \
     libssl0.9.8 \
     libssl-dev \
     openssl \
     ssl-cert

(Thanks to the Ubuntu forums for tips on the SSL library packages)

4. Configure the build

Override defaults pointing to older versions of GLib and GTK, then generate the makefiles and other build configuration.

export GLIB_LFLAGS=-lglib-2.0 \
export GLIB_CFLAGS="-I/usr/include/glib-2.0 -I/usr/lib/glib-2.0/include" \
export GTK_LFLAGS="-lgtk-x11-2.0 -lcairo -latk-1.0" \
export GTK_CFLAGS="-I/usr/include/gtk-2.0 \
                   -I/usr/lib/gtk-2.0/include \
                   -I/usr/include/cairo \
                   -I/usr/include/atk-1.0" \
export pango_LIBS=-lpango-1.0 \
export pango_CFLAGS=-I/usr/include/pango-1.0 \
export CFLAGS="$GLIB_CFLAGS $GTK_CFLAGS $pango_CFLAGS" \
./configure

Add a “–prefix=DIR” option to the configure command if you prefer to specify a custom installation directory.

5. Build the software

make

If that doesn’t work, redirect the output of “make” to a file and search for the string “errors:” to see what went wrong:

make > OUTPUT 2>&1

6. Install the software

sudo make install

If you ran the configure script with a custom prefix option pointing to a directory that you can write to without root privileges, then you can run “make install” without the “sudo”.

7. Done

So that’s it. If you are upgrading from Gaim 1.5, all of your configuration will be copied from the .gaim directory to .purple in your home directory. Your log files will also be moved, but a symbolic link will point from the .gaim/logs directory to the .purple/logs directory.


More about the name change from Gaim to Pidgin:

Pidgin project leader Sean Egan describes the new name in an interview with Ars Technica:

“We like the name,” Egan told me. “It was the second choice we all really liked. We were thinking up linguistic terms, and someone mentioned Pidgin. Another developer commented that ‘corrupted language’ may not be the best thing to associate yourself with, to which another pointed out something along the lines of ‘have you ever SEEN people talk on IM?’”

“We all felt that was a pretty valid point, so the name stuck,” continued Egan. “It’s a corrupted language, much like that used by IM users, it’s caused by people talking different languages (or protocols) with each other, and it sounds like a bird known for carrying messages across long distances.”

Also, AOL agreed to stop threatening the project with legal action if they changed the name.


Apr 25 2007

Wiki Tips: Joining an Existing Wiki

It can be disorienting to start contributing to a wiki for the first time, especially if you have used email and document repositories for all your previous electronic collaboration. Here are some tips to help you get started.

1. Find the local landmarks

A wiki server does not provide any intrinsic structure for organizing collections of pages. Teams find different ways to create their own structure. Some wiki software allows pages to be arranged into hierarchical trees, which may not be obvious from the default user interface configuration. You may need to configure your settings to show the hierarchical relationships between pages, or select a specific link to see a tree view the pages. Here’s how you do that for Confluence:

Even if the software supports page hierarchies, some teams may prefer to use a flat structure with a web of links between pages. If that’s the case, find the pages that serve as hubs and main entry points. For example, here are two entry points to the original wiki server:

2. Create pages by linking to them

Here’s a time-saver for creating a new page with a link from an existing page. Edit the existing page, add a link to the new page (which doesn’t exist yet), and save your modification. Click on a link to a non-existent page, and you should get the page editor with the page’s title filled in.

This is also useful for creating an initial outline, leaving the actual pages to be created later.

3. Publish drafts early

“The best reason for putting anything down on paper is that one may then change it.” – Bernard De Voto

The wiki and its pages are the most recent draft of a living document, always open for rewriting.

Add content as soon as you have enough material to create an incomplete rough draft or even an outline. Leave markers where you plan to add more information or exposition. Other people will sometimes fill in the missing text, but don’t rely on it – you might be disappointed. More importantly, early drafts provide clues about how you are thinking. Your team members may be able to share insights that save you time or open up interesting new possibilities.

4. Sign comments, not content

Writing for a wiki should be in the style of a document, rather than a conversation. (This doesn’t apply if you are writing in the form of a dialogue for pedagogical or dramatic reasons!) When inserting comments into the middle of a page, like attaching sticky notes to a paper document, feel free to sign your name. If you have comments at the beginning or end of a page, like notes in the margin, it may also be appropriate to leave your name. That tells your collaborators who to talk to about the comments. However, it is probably best to have that discussion on a mailing list visible to the whole group. In that case, it doesn’t really matter if the comment is signed. Resist the urge to put your thumbprint on a piece of content that says “I wrote this!”. That clashes with the collaborative spirit of a wiki.

5. Trust the history features

You might be tempted to leave old content in a page, even if it’s no longer valid. That’s usually a bad idea, especially if it leaves multiple versions of the same text on the same page. If information is obsolete, update it or remove it. You can explain your changes to the team in an email, or possibly in a revision message that the wiki stores in its history.

If people reading the wiki page need to know that some information is no longer valid, then document that on the wiki page.

Most wiki software allows you to view old versions of a page, view the dates and authors of previous changes, and view the differences between two versions. Use those features to look at a document’s history, and keep the latest version of the document clean.

6. Put everything in the wiki (unless you have a better place for it)

Capturing information is the first step toward sharing it. If you don’t already have a system designed for storing some type of information, put it into your wiki. Most wiki software allows files to be attached to wiki pages, so you don’t necessarily need to have a separate document repository. The goal here is to make all information available to the whole team. Don’t hoard it on your private email files or local disk drive.

7. Learn to export

If you want to freeze a version of some wiki content, export the pages to PDF or static HTML pages. Your wiki server probably provides some export capability. If not, you can use your web browser or some other tool to download the web pages for safe keeping.

This is also useful for sharing private wiki pages with people who can not access the wiki directly.

8. Watch for recent changes

Good wiki software allows you to subscribe to email notifications for an entire wiki or individual pages. Register for notifications of any area of the wiki that you are working with. You may also want to subscribe to RSS feeds, but only do that if you will actually read them as part of your normal routine.

9. Try editing “raw markup”

After you have become comfortable editing wiki pages with the rich WYSIWYG editors, try editing the raw “markup” text. Wikis traditionally provide a simple notation using plain text to represent formatting. For example, placing asterisks (*) around a word may cause it to appear in a bold font. You may find that it makes creating complex wiki pages faster and easier. Or you may hate it. Still, it’s worth a try.

Some wiki software only provides this type of raw “markup” for formatting. If that’s the case, you are likely to hate it at first. Give it time. It could grow on you. If not, lobby to upgrade to more modern wiki software. MediaWiki is one of the few popular wiki servers that doesn’t offer WYSIWYG editing by default, but even that has a plug-in that can add rich editing from within a browser.

10. Know when to pick up the phone

And lastly, some common sense. If the collaboration is stuck, or if there are conflicting opinions that can not be resolved through comments in the wiki pages, then resolve the situation by communicating directly with your fellow authors. Have a conversation in person, if you are in the same location. Otherwise, you have several options for communicating: email, instant messages, and the telephone. A wiki can be great for collaboration, but it’s not always the most effective tool for communication.


Apr 17 2007

Lack of Propinquity

When is a co-located team not co-located?

(Or “colocated”, if you prefer. Or even “collocated”.)

The phrase “100 co-located developers” came up in conversation the other day. It was said in passing, but I had a knee-jerk reaction and started spouting off about how that many developers can’t be effectively co-located. (Hopefully my schpiel didn’t go on too long, because it wasn’t really the time or place to get into the subject. That’s what this blog is for!) In a large organization, some people will inevitably be far enough from others that they can’t be considered co-located. They may be at the same site, but not close enough to have chance encounters in the hallway and arguments over who left the coffee pot empty.

MIT’s Tom Allen found that communication between engineers is strongly influenced by the distance between them. This relationship is described by the Allen curve which indicates that engineers located more than 50 meters apart don’t communicate with each other any more than people in separate cities. This has been corroborated in other domains since the original research in the 1970’s. These findings have been used to design better physical spaces for teams to collaborate and innovate. Cool stuff.

Further reading: