Sunday, December 4, 2011

The Story of Live-Noting

Like a lot of people, I've got this thing I do when I attend conferences, meetups, classes, and tutorials: I take notes. My open source based ones are mostly written in RestructuredText and I've kept in a particular folder since at least 2006.

Putting notes in a DVCS

On September 13, 2009, I uploaded these notes to Github.com. I did that because I wasn't pleased with the workflow I established of moving items to Dropbox for backup. I use DVCS all the time and I figured why not just put my notes where I put my code? So I added my notes as a Github repo.

DVCS Notes Based Management System?

For a while I tried to use the Github folder README.rst trick to make a navigations system for my notes. But Github isn't designed for making a README into a dynamic custom content navigator, and it would make a silly feature request. I would rather the Github team work on Mercurial integration or other practical things before they honored a request to turn their system into my own custom Notes Management System. Eventually I just gave up on it and moved on.

Sphinx + Read The Docs!

In early July of 2011 I had a wicked fun thought. What if I turned my notes into a Sphinx project and posted it on readthedocs.org? Most of my content is in RestructuredText and I've gotten really fast at rolling out Sphinx documentation. The 'hard' part would be converting the few README.rst files into index.rst files, but on the flip side I could use fancy Sphinx directives.

I'm not exactly sure when I started down this path, bit this commit log entry leads me to think I had it working on or around July 8th. What that would mean is that every time I pushed up a change in my notes, within minutes readthedocs.org would publish the content to the world in lovely HTML markup.

The result?

Pydanny Event Notes


Here's a screen shot of the front page


PyCon Australia 2011 Test Drive

For the 2011 PyCon Australia I gave my new process a serious whirl. I found if I created the page before the talk and entered some basic data like author and title and tied it to the index then I could constantly check the quality of my output while taking my notes. It made my notes seem a bit more exciting and alive. I even tweeted about it cause I thought it was fun, and people around the world seemed to enjoy the effort I was putting into my notes.

Because I was committing constantly in order to get updates on readthedocs.org as soon as possible, I also adopted the habit of super-short pull request messages. That's because the content I'm writing overrides the need for verbose comments. So when you see me writing "moar" it's because every minute or so I'm doing something like:
$ git commit -am "moar"
 $ git push

Kiwi PyCon 2011

I did my rapid note taking again at Kiwi PyCon and it was fun. The downside was that sometimes I get rather critical in my notes and I had a couple speakers come up to me later to clarify their positions. This makes it a bit challenging because I want to put down my thoughts, but if my thoughts impact another person, what should I do? Especially since if my negative notes on someone turn up in a search it can negatively impact the speaker way beyond a single talk. This is now always on my mind when I take notes, and I'm trying to figure out a good way to handle this going forward.

In essence, I don't want to constrain what I write but I also don't want to write something that will haunt someone else later. Even with a caveat and all that stuff, it can still be problematic. There is a difference between me ranting about something and me taking notes, and the written word is such that things are all too often taken out of context.

Food for thought indeed.

DjangoCon 2011 and the invention of the term 'live-noting'

At the start of DjangoCon 2011 someone tweeted that they were planning to 'live-blog' the event. Suddenly I realized that what I was doing had a name for it, and that was 'live-noting'. So I tweeted that was what I was doing and it seemed to catch on.

Not only that, but I got asked if I would accept pull requests. After a good two seconds of deep thought, I responded that I would only consider corrections and clarifications, not new material. I received not just one, but two pull requests from good friends and left the conference pretty happy.

On top of that, I managed to get featured on the front page of http://readthedocs.org! (Thanks Eric)

Kenneth Love also took notes in a similar fashion: readthedocs.org/docs/djangocon-2011-notes

PyCodeConf 2011

I had the excellent fortune of being an invited speaker to Github's PyCodeConf. While I gave my talk, my lovely fiancée, Audrey took notes of my talk and submitted a pull request. Her contribution was the first time I accepted content I did not write, and I'll say right now she's the only one for whom I will accept such content. On the other hand, If you take notes when I present let me know and I'll link to them from my own notes.

Josh Bohde also took notes at the event in a similar fashion readthedocs.org/projects/joshbohde-event-notes and even as I write this post he shares the featuring of our notes on the frontispiece of readthedocs.org:


Closing Thoughts

I often use my notes as reference, and if you follow the commit logs you may even see me comment or clean up things I wrote down years ago.

The graphs and stats of this effort is really interesting. Fortran? And a total of
Five contributors!

All of this makes taking notes a lot more fun. I enjoy finding ways to enhance and improve my process, and find it exciting that others are following a similar pattern of effort. My hope is to make 2012 the Year of PyCon, where I find a way to go to a Python related conference on six continents (Antartica is too cold for my tastes) and take notes everywhere.

Going forward, should I document how I built this out? Would my steps and patterns be useful for others?

4 comments:

Unknown said...

Interestingly, it was your live-note efforts that made me realise the potential for BitBucket+ReadTheDocs to address my dissatisfaction with Blogger as a forum for longer form, more permanent essays:

http://readthedocs.org/docs/ncoghlan_devs-python-notes/en/latest/

Christopher Grebs said...

You're notes are always just awesome and I love reading about all the conferences in detail and even though I cannot attend most of the time I get the important bits.

Thanks for that!

But you're notes always have a downside - they make me feel bad I've not been there :-)

Wes Mason said...

You could always host your notes in a Github wiki (as powered by the Gollum project) then you can just commit notes in a git but have a hwst do and indexed wiki front end for the files (including .rst's).

pydanny said...

@Wes - Github wiki is great. But I want to edit my notes in a text editor and use git as my DVCS on my notes. This makes my notes EXTREMELY portable. I can work on them whether or note I have Internet. And if I need to move them off of Github then doing so is trivial.

I've kept these notes forever because of their portability.

As soon as I go to a Wiki system I lose all that. And migration between systems becomes hard.

Of course, everyone has their own style. Use your system and live-note your next attended event! :D