Tag: notes

April 8, 2013

Write the Docs: Kenneth Reitz – Documentation is King

I’m at Write the Docs today in Portland and will be posting notes from sessions throughout the day. These are all posted right after a talk finishes so they’re rough around the edges.

Kenneth, who works at Heroku, kicked off the morning at Write the Docs. He started his talk by stating that, “Constraints foster creativity.” It’s about the simple things: prime lenses, mechanical watches, pen and paper, etc. In his code and documentation he aims for pragmatism and constraints. If you try to build something that works for everyone’s use case it causes a bad experience for all.

With Kenneth’s Requests tool, he took this approach. What makes a code package popular is the API. All other things are secondary. Developers spend hours every day working with your APIs. If you don’t put a high level of craftsmanship in to those products you’ll only be frustrating your most frequent users.

Documentation is what helps your API grow without becoming compromised. Before any code is written, write the README – show some examples. Then, you should write some code with the theoretical code that you’ve just documented.

Kenneth relates this approach to responsive design. A README-driven API design is responsive to the needs and use case of your users.

He quoted Pieter Hintjens who said that, “Simplicity is always better than functionality.”

Documentation is the glue that makes open source projects possible. As Kenneth put it, if you got to a page and don’t know what problem the code solves then the project has failed. Documentation helps you to explain what problem your code is solving.

Technical debt, code inconsistencies, and many other aspects of internal development issues stem from poor documentation. Both open source projects and internal code are essentially useless without documentation.

Documentation, for Kenneth, leads to better code, a better workplace, and a better lifestyle. It allows more asynchronous workflow where coworkers can dive right in to a new code project without needing to bother someone else about how the API works.

April 6, 2013

I wish I had all my notes from college in plaintext Markdown-formatted files. As I get back in to reading more difficult texts I’m writing up chapter notes in nvALT.

The more I do this, the more I find myself going back to them and searching for previously noted phrases, definitions, or quotes. My reminiscent wish is for nvALT to be a single data store for all my reading annotations. The problem is I have all these NeoOffice and Pages files from college.

February 2, 2013

If Mayors Ruled the World

I listened to the Long Now Foundation lecture from Benjamin Barber this afternoon. The lecture, titled “If Mayors Ruled the World,” is an interesting look at the growth and power of cities that I’d highly recommend listening to. I took a few scattered notes below. Enjoyed this a lot more than his book, Strong Democracy, that I read in college.

Around 40 minutes in there’s a section on global city growth that is fascinating. The stats he cites are mind-blowing, particular those around Chinese cities.

One of the main discussion points in the lecture is whether states or cities are more capable of governing on the global stage. Barber answers it by saying,

States cannot govern globally, that much is clear. Cities can and are.

As part of this cities must come to rely upon each other more directly as that’s the path to security and sustainability. To do this, though:

Cities cannot wait for states to figure out the meaning of interdependence.

In the Q&A he talks about Singapore’s subsidized home ownership process. It’s a pretty interesting idea that’s counter to how the US has approached affordable housing. In Singapore, the city basically subsidizes the construction and ownership of apartments instead of just their rental. What Barber describes this as doing is creating a wide group of stakeholders in the city’s future.

Toward the end of the Q&A Barber talks about why mayors don’t move on to more national government positions as frequently as one might expect. As he put it, “Ideology has very little to do with running a city.” Many mayors are more politically independent and, thus, don’t succeed as well on the national stage, where success is more determined by adherence to party line.

January 15, 2013

Status

Rediscovering the beauty of Simplenote has done wonders for my memory and productivity. Paired with Notational Velocity it’s unstoppable.

October 18, 2012

Notes from UserConf

Last Friday I was in San Francisco for the first ever UserConf. It was a fantastic day filled with great speakers and fun conversations. Like I mentioned on Twitter, it was the best conference I’ve been to in a long time.

The wifi was sketchy during the day so I just kept my notebook, the paper kind, handy for jotting down ideas from the talks.

Richard White, co-founder and CEO of UserVoice, opened the day by talking about the current state of customer service and what motivated UserVoice and CoSupport to put on UserConf. He characterized businesses as defined by two types of support: the traditional model and the web-native model.

The traditional model of support is that which grew up with older businesses. It’s massive call centers, phone trees, and a world where only 29% of companies reply within a day and only 20% reply across multiple mediums. It’s a world defined by ITIL and other arcane acronyms.

The new, web-native mode of support is what grew up alongside the internet. It’s fast-paced, multi-medium, and focused on opportunities. 83% of companies reply in under a day, 89% reply across multiple channels, and 87% reply on Twitter. This model of support is one that gets back to business basics and is an integral feature of your product.

Richard also set down the guide for the rest of the day’s talks. As he put it, no one goes to school for customer service but everyone at UserConf knows it’s vital to their businesses. For that reason the day was going to focus on the how of support, not the why. It wasn’t going to be a day about arguing why you should reply to customers over Twitter. Instead it would focus on how you can craft kick-ass experiences for all of your customers, every day. If you can keep your customers happy you can keep your customers.

Jessica Semaan, from Airbnb, was the next to speak. She talked about how Airbnb was able to scale its customer support team from 3 to more than 200 people. Jessica described it all through a metaphor relating customer service to a love relationship.

At Airbnb they started with all support running through the founder’s cell phone. That didn’t scale so well. As they grew the team they wanted to find a way to help more people more quickly while still having the high level of service and trust.

To get started they set trust as their defining goal. As part of that they hired people from within the community, those who were already hosts or had frequently stayed with hosts. They spent 6 months consolidating data from Zendesk, Contactual, and other services they were using. As Jessica phrased it, they need information not data. They want to be able to track contacts per transaction, top issues with each product and team, and cost per support interaction.

Jessica also talked a lot about what phone support is like at Airbnb. Multilingual phone support costs six times what offering multilingual email support does. Once you offer phone support you then need to offer it in many timezones. Each of those timezones need someone for each language you support. Suddenly your 2 person support team becomes 12.

Later in the day Kevin Hale, co-founder of Wufoo, who talked about how they designed software that people loved using. He opened by describing Wufoo as “Microsoft Access as designed by Fisher Price.” Pretty awesome.

From Kevin’s talk, everything about Wufoo seems extremely well-crafted and focused on providing a stellar experience. They keep response times to around 12 minutes, which is phenomenal. The “Help” tab within the interface goes directly to the relevant documentation.

One of the best tips Kevin mentioned was how they include an “Emotional state” choice in the support contact form. 76% percent of their users filled it out versus the 78% who filled out what browser version they were using. Customers also didn’t game the system by always marking “frustrated” or “angry.” On the whole they used it honestly.

Later in the day Kevin posted the full slides from his talk over on Speaker Deck. Check them out, there’s some great stuff in there.

Chase Clemons also talked about support at 37signals. His talk was filled with lots of tips, tricks, and words of advice. One of the first things he mentioned is that every product on the web should have domain.com/help redirect to support docs. 1

He also talked about how 37signals, while not providing phone support on a regular basis, still uses it for certain cases. Chase’s guideline is that if something takes more than 3 replies with the customer he’ll work out a time to chat with them over video and/or screenshare. meetings.io was mentioned as a tool for doing this. It lets you spin up on-demand video meetings.

37signals has also started experimenting with live, online classes. They do two, 30-minute classes a week; one is about becoming a Basecamp pro and the other is a general Q&A. Over the last 8 months they’ve helped more than 10,000 people this way. Pretty amazing when you think about it.

They also did the first ever Basecamp Delivered event last month in Austin. That was an all-day, in-person help session for anyone in Austin who had questions they needed answered with Basecamp. They had two rooms with 30-minute time slots in each where people could come by themselves or with their entire team and learn more about Basecamp. I love that idea.

Most of the speakers at UserConf were from relatively small web companies. Doug Turnure was not. He’s a Visual Studio Program Manager at Microsoft where his team has 100 million users. At that scale, as he said, support becomes all about having the right conversations with the right people at the right time. One of the things they’ve done with Visual Studio is to add in-app recording and annotating so that bug reports come in with more detail. Doug’s talk was fascinating. Learning how a 4,000 person product team develops and supports something as big as Visual Studio is mind-blowing.

There’s also a recap post up on the CoSupport blog with more notes and links to everyone’s slides.

Overall, UserConf was fantastic. The best conference I’ve been to in a long, long while. They’re planning on holding another one in the Spring of 2013. If you’ve made it all the way to the bottom of this post then you should be at the next one.

Notes:

  1. I’m happy to say WordPress.com does this. 🙂 ↩

April 28, 2012

Defining new metrics for journalism

Greg Linch led a session in the morning at BCNI Philadelphia about how we can define new metrics for journalism. It was prompted by the similar post he wrote earlier this year.

To help we need to look at the metrics other industries are using to define success in their work. Greg’s idea stems from Alexis Madrigal’s notion that you have to define your own metrics. You can find influence from others but don’t just adopt their method.

We have methods for measuring how many people see our work and how long they spend on a site. But, we don’t have solid metrics for measuring the impact of journalism. As Greg said, “What does a pageview mean?” The metrics we currently have mean things. They tell us how many, how long, and other aspects of our work’s impact. But they are largely one-dimensional and don’t tell the whole story.

Current approaches

Altmetrics.org was mentioned as one different approach. As their site says:

Altmetrics expand our view of what impact looks like, but also of what’s making the impact.

Sabermetrics was the focus of the Moneyball movie and is a similar approach in sports to redefining the metrics of an industry. Things like VORP and OPS bring new light to the performance of athletes who may appear successful by traditional metrics.

Propensity score matching is yet another approach. Tries to answer the questions of, “What’s the possibility of X to happen based on Y?”

Greg also metioned the way the Cleveland Orchestra measures performance. They strive toward superior performance and measure it by standing ovations, ticket demand, and more.

Someone in the audience mentioned the way Gawker rotates staff. Nieman recently wrote a bit about this. For a different way of rotating staff check out how The Economist does it.

Ideas

Someone mentioned that one way to approach this is asking readers the question “Do you understand this issue better after reading this article?”

I brought up the way KISSmetrics approaches site stats from a user-specific perspective. For journalism that could be looking at how many people read the first story your publish on an issue and all of the followups. You could also measure how many jump from one report you’ve published to another one on a different topic.

Greg mentioned the net promoter score that many organizations use to measure the loyalty and reputation of a company or a product. One person in the room works at an organization which uses this on a per-brand basis. They separate the content creation from the content display. Each coverage team is given a net promoter score as well as each product or brand their content is flowing through.

The concern over not being able to measure impact in communities that are not online was also raised. Ultimately the way to fix this is to get out in the communities and talk with people about whether they understand issues and how they’d like to learn more.

Albert Sun said that part of why metrics are so confusing is because they are traditionally geared toward what advertisers want. The predominant approach is, “All metrics are good but we need to make money off of them.” The business side is failing, though, and what we need to do is create a new, better model. What we need is a way to measure the difference and change our journalism causes in the world.

If anyone has more to add feel free to leave your own notes as a comment.

August 6, 2011

WordCamp St. Louis: The Anatomy of a Premium WordPress Theme

Brian Fegter gave a talk in the afternoon discussing WordPress premium themes. Brian runs Mister Nifty where he works with churches of all sizes on their tech needs.

He got started by covering the truth about commercial themes. As he says:

There is not one single theme that does not require support. You must build a support system

Brian also believes that software development needs to be for the customer. This is why support and documentation are so important. As he pointed out, a purchased theme rarely stays in its original condition.

Having a solid template architecture is also fundamental to creating a good premium theme. Brian pointed to the WordPress Codex for information on theme development and template hierarchy.

Brian set down a credo for properly developing a theme. He believed that you should:

  • follow template hierarchy patterns
  • clearly name supporting files and folders
  • never, never, ever, never, ever nest a plugin inside a theme
  • clarity over cleverness

WordPress assets are your friend when coding a theme. There’s a lot that is built in to WordPress which will let you easily enhance a commercial theme without a large code footprint. The main things discussed were:

  • clearly named sidebars
  • custom post types only when necessary
  • define theme locations for menus
  • localize your strings
  • set WP image sizes vs image resizing scripts
  • leverage the power of CSS with body_class() and post_class()

He also showed off some cool functionality in the UpThemes framework that’s available on Github. There’s lots of sweet stuff built in there for Google fonts and more.

In some ways code is narrative. Your theme tells a story and has an intended result. The back-end code should clearly narrate the story of the front-end display. All this helps because clean code leverages the brain to quickly identify and associate words with functions.

Functions though need to use prefixes and should only try to accomplish one thing. If any function includes things that can be spun out into a separate function then they should be spun out that way. For code comments with functions Brian says that:

If it’s necessary to comment about how a function works, your code stinketh.

It’s also a good idea to use built in functionality for things like browser detection and content filtering. This keeps you from having to add lots of server overhead and user frustration. In other words, we should be creating useful code, not duplicate code.

August 6, 2011

WordCamp St. Louis: WordPress for Writers and More

Shawntelle Madison gave a talk at WordCamp St. Louis titled “WordPress for Writers, Publishers, and other Content Providers.” Shawntelle is an urban fantasy writer with a new book coming out. She also works with design firms in St. Louis and has been working with WordPress for over 5 years.

With her book coming out Shawntelle has seen both sides of the coin with what publishers require from author websites.

WP in the publishing community

It’s a lot more prevalent than you first think. Shawntelle polled 47 authors from various genres and 85% were using WordPress. The user-friendly Dashboard, ease of theme changes, and flexibility with widgets and plugins were favorites.

They also like it because it’s far easier than coding a site from scratch. When your job is writing content you don’t want to be spending all the time coding and designing your site.

Branding

Shawntelle said that “branding is very important for authors.” The design is what readers first see and it should really fit with the genre of your writing.

A great example is Scott Westerfeld who has a site which fits his steampunk style writing quite well.

What’s common

Authors expect a few key features for almost every site. They like having things like:

  • Newsletter integration
  • The ability to add a backlist of books
  • Integration with social media
  • Other basics like ad management, contact forms, and a well-designed blog

Most authors Shawntelle works with already have had some experience with WordPress. They don’t want a complex front-end layout and prefer to keep things simple.

Determining who is responsible for site maintenance is key to any project you work with an author on. Many won’t keep the site updated so figuring out who will be responsible for that going forward is crucial.

Shawntelle also mentioned some of her favorite and most useful plugins from projects with authors.

Publishers

Out of the 6 big publishers 2 are running WordPress in their work.1 Random House and Hachette use WordPress to power parts of their imprint on the web.

For example, Random House uses WordPress to power their At Random site. There’s tons of reader guides, audio and video, as well as links to the books in the Random House catalog.

Data from the existing Random House catalog was used to power things like the New Releases slider and more on the site. They also link up to services like Goodreads, Shelfari, and LibraryThing.

  1. The big 6 are Macmillan, Random House, Penguin, Simon and Schuster, Hachette Books, and HarperCollins.

July 17, 2011

Marginalia on Post-Artifact Books and Publishing

Author’s note: A quote or a few sentences about a piece make up many of my posts here. This time I’m trying something new. Consider it an experiment in turning my blog into a type of digital marginalia. I’d love to hear what you think about it.

A rainy Sunday in Portland seemed like a good time to sit down and read Craig Mod’s essay Post-Artifact Books and Publishing. In a word it’s brilliance. Craig nails it. It’s such a thought-provoking piece that I wanted to make some notes. All quotes come from the essay unless otherwise noted.1

Natively digital

Take a set of encyclopedias and ask, “How do I make this digital?” You get a Microsoft Encarta CD. Take the philosophy of encyclopedia-making and ask, “How does digital change our engagement with this?” You get Wikipedia.

Great observation. Like much of the essay the driving point is that digital becomes powerful when it is not shoehorned into analog conceptions of artifacts. A book is a book (or a newspaper a newspaper) because that was what the technology used to best allow for. With new technology we will redefine our artifacts of information.

This quote also made me think of what we call “online learning” today. For the most part I think we’ve taken our idea of instruction in college and high school and placed that into online tools. What we’re missing is the form of instruction that stems from asking, “How does digital change what we can do with information, instruction, and learning?”

Publishing for all

We cannot know how much magnificent culture went unpublished by the white men in tweed jackets who ran publishing for the past century but just because they did publish some great books doesn’t mean they didn’t ignore a great many more … So we’re restoring the, we think, the natural balance of things the ecosystem of writing and reading.

That bit’s from Richard Nash of Red Lemonade. The more voices we have the better.

Reminds me of something Fred Wilson has written about multiple times: everyone deserves a printing press. He writes that:

If I look back at my core investment thesis over the past five years, it is this single idea, that everyone has a voice on the Internet, that is central to it.

The more pieces of information we can have publicly available in the world the better.

Shared experience

But — and here’s the real magic — it’s a shared telepathy. A telepathy from one to many, and in that, the many have experiential overlap. Printed matter binds this experience to pulp. With digital, there is the promise of networking that shared experience.

That’s a really cool point. It brings to mind the video IDEO produced on the future of the book. When a text can connect us to others in a shared experience that leads to really powerful possibilities.

This is similar to something Whitman tried to do with it’s Freshman year CORE class. The goal was to create a shared background of foundation texts that could serve as a common frame of reference for the 4 year experience. A problem in that, and in other experiential overlaps that are dependent upon printed texts, is that it requires a common place and time. Digital blows that wide open. Our networking allows us to share that telepathy in real-time or asynchronously from wherever we are.

  1. A note on this: writing up notes on something as complex as this essay has made me once again wish that emphasis was by default on the web. Since it’s not command + F is your friend to find these quotes.

October 11, 2010

Forked version of Notational Velocity

If you are a fan of Notational Velocity, a forked version was released today. It adds things like full screen mode and some other nifty views. I’ve used it for notes today and have to say that the full-screen edit mode is pretty slick.