Productivity and Note-taking

I told a friend of mine that I wasn't really happy with the amount of time that gets taken up by Slack and "communication and scheduling" in general, and that on one particularly "noisy" week it had taken up around 7 hours. He said that was "hardly anything" and that most of his work was done via Slack.  He has a support role, so I guess that makes sense. So it definitely can be a useful tool, but in the past few weeks I've managed to keep Slack usage down to about 3 hours per week.

On a related topic, I've tried a bunch of different task management techniques over the years and none of them ever stuck. I've always ended up with a fragmented collection of things to do, scattered between various Notes apps, email-based task lists, Trello boards, and hand-written notes.  The problem with a lot of the software-based task management options for me is that they're not always in front of me and they take a conscious effort to open and use.

A notebook on the other hand is always on the desk beside me, usually open to the last page of notes. There's no effort getting to it, and I can easily glance over without disrupting whatever I was doing on the computer.

There's a system called a bullet journal for keeping and managing lists.  The website bulletjournal.com explains the system and has an online store with their BuJo journals that are designed to work with the bullet journal system. There's also an app, so for people who really want to get into it, there are a variety of ways. You don't need a special BuJo journal to start using the technique, however.

I've switched my list of tasks from an online document to my pen-and-paper bullet journal now. I'm not fastidious about keeping the journal up to date on a daily or even weekly basis, but I find that its just a lot easier to take notes this way than it was to type things into a digital form.  The only downside I can see is that it's harder to share than digital notes which can be copy and pasted. But frankly most of the tasks on my list are too detailed and boring for anybody else to care about. They just want to know how a feature is coming along, etc.  So, check out the bullet journal.

Slack is a major productivity drain

For the past few years I've been using RescueTime time management software.  It helps keep track of the different activities I've spent time on during the work week and stay focused on things that contribute to my productivity.  Another application that's become a big part of many workplaces is Slack. We use it for communication in my current team. A lot of times, it's really helpful. You can fire off a quick message and get a quick reply without really interrupting your main task. A lot of times you can ask a question, get valuable opinions from everyone concerned, and come up with a consensus that works for everybody, in a way that would've been impossible with traditional email and meetings.

Recently though I was shocked to see that Slack accounted for a full 7 hours of a recent work week. We've been doing a lot of planning and discussion for new feature work, and also working through some issues related to customer documentation, deployments, and things that are not specifically coding-related, so it's understandable that there's been more planning and discussion activity than usual, and less actual code-writing. But 7 hours!  My gosh.  That is a real time sink.

This was a wake-up call into something that I already intuitively knew, that Slack - as helpful as instant messaging can be - has the potential to be a black-hole where productivity gets sucked into a terminal death-spiral.

The challenge is how to reign in this Slack tyranny... if you don't monitor the conversations going on in various Slack channels, you're liable to miss out on vital information. A lot of people seem to think that broadcasting a message out on a Slack channel is "job complete" when it comes to communication - a surrogate for the old-school email.  That's not really the case; messages easily get lost in the backlog of noisy, run-on chatroom conversations.

I'm going to be keeping an eye on Slack usage and trying to figure the best way to keep it from sucking up a large percentage of my productive working hours without losing the benefit of instant communication with the broader team.  Maybe just being respectful of people's time and being a little less cavalier about using Slack to post casual commentary, understanding that Slack can definitely become a drain on my own and other people's time, and approaching it as a tool to be used with a certain level of professional self-restraint, might be a start.

REST API Best Practices 5: Further Reading

Since I started writing on REST API Best Practices there have been some interesting new developments. Going forward we'll take a look at some of them, covering things like documenting APIs, how to define relationships between different resources, and various tools that - while not specifically REST-related - are useful for working with JSON as a data interchange format.

In the meantime, here's a list of articles that provide more information on a lot of the concepts that were outlined in the first four posts on REST API Best Practices. No doubt a lot more has been written about REST APIs in the last few years, but I think these resources are a pretty good window into some of the original sources that shaped the best practices used for REST API design today.

If you want to suggest other articles please feel free to comment below (note that comments are moderated and won't appear immediately).

Tutorials
http://www.restapitutorial.com/
http://obeautifulcode.com/API/Learn-REST-In-18-Slides/

General best practices
http://www.restapitutorial.com/
https://zapier.com/learn/apis/
https://s3.amazonaws.com/tfpearsonecollege/bestpractices/RESTful+Best+Practices.pdf
http://apigee.com/about/api-best-practices
http://www.vinaysahni.com/best-practices-for-a-pragmatic-restful-api
http://www.slideshare.net/mario_cardinal/best-practices-for-designing-pragmatic-restful-api
http://apigee.com/about/api-best-practices/restful-api-design-second-edition
http://devproconnections.com/web-development/restful-api-development-best-practices
http://www.restapitutorial.com/
http://madhatted.com/2013/3/19/suggested-rest-api-practices

HATEOAS
http://restcookbook.com/Basics/hateoas/
http://timelessrepo.com/haters-gonna-hateoas

HAL
https://en.wikipedia.org/wiki/Hypertext_Application_Language

Documentation best practices
http://bocoup.com/weblog/documenting-your-api/

Partial updates:
http://stackoverflow.com/questions/232041/how-to-submit-restful-partial-updates
http://restful-api-design.readthedocs.org/en/latest/methods.html

Misc
http://www.wekeroad.com/2012/02/28/someone-save-us-from-rest/
http://docs.couchdb.org/en/latest/api/basics.html#api-basics

Auth
http://www.thebuzzmedia.com/designing-a-secure-rest-api-without-oauth-authentication/
http://en.wikipedia.org/wiki/OAuth
http://restcookbook.com/Basics/loggingin/
http://broadcast.oreilly.com/2009/12/principles-for-standardized-rest-authentication.html
http://stackoverflow.com/questions/630538/designing-a-web-api-how-to-authenticate
http://en.wikipedia.org/wiki/Session_hijacking#Methods
http://apiux.com/2013/03/21/authentication-dont-be-clever/
https://developer.github.com/v3/auth/
https://github.com/blog/1509-personal-api-tokens
http://stackoverflow.com/questions/7999295/rest-api-authentication
https://www.google.com/search?client=ubuntu&channel=fs&q=api+authentication&ie=utf-8&oe=utf-8