Tag: conferences


One of the things I’m most proud of from this year was helping to organize the first ever SUPCONF in San Francisco. I spoke about how to build a career in support and helped plan pieces of the event. It was amazing to see a Slack community come together in-person and connect.

Later this month we’re holding the next SUPCONF in New York City. Over two days we’ll host speakers from Medium, SmugMug, Wistia, Help Scout, Automattic, and more. Beyond that we’ll have dedicated time and space to talk with other attendees.

That time and space for connecting with attendees was one of the things I was happiest with from SUPCONF SF. I think attendees walked out of the two days having gotten to know far more people than a traditional conference would have allowed for. A hallway track can be great for outgoing folks. Being intentional with how it’s organized, though, can give even those who aren’t outgoing the confidence to engage.

We also have many other events happening around the conference. From a pre-event cupcake social to a GIF battle to a hosted dinner and conversation there’s a lot going on.

If you find that interesting I’d recommend registering soon while there are still a few tickets left.

An open letter to conference organizers. Set of tips from Scott Berkun on how best to help speakers help your conference. Really helpful to read through as I think more about SupConf.


I’ve worked in customer support for almost 9 years. When I started it was just something I enjoyed doing. I liked tinkering with technology and figured, why not use my experience to help others? Pretty quickly I realized I would be very happy if I could find a way to do this for a long, long time. Customer support is my career.

That’s why I’m beyond thrilled to help Scott and others plan SupConf, a conference for folks who want to build a career in support.

I’ve written before about how customer support, when done well, is a career. SupConf is about how to make that happen.

The event is May 23rd and 24th. It’s two full days of well-considered talks that will impart lessons for you to take back to your day-to-day work. Plus, we’re designing the event with conversations and opportunities to meet others in mind. Speakers are important, but they aren’t the whole event.

If that sounds interesting, I’d highly recommend signing up for the newsletter. In the meantime, you can read about some of the themes we’re looking to cover.

It’s time we think about support as more than just an entry-level job. Support is a career, a craft, and something to be proud of.

Documenting Conferences

Last week I attended Write the Docs. As with previous events I took real-time notes of the talks. Over the last two years that resulted in 32,515 words of notes. It seems fitting to spend so much time documenting a documentation conference.

The ephemerality of conferences frustrates me. Events bring a knowledgeable group of people together. During the conference energy and ideas are palpable but when attendees go home that all fades in to the ether. The occasional slide deck makes it online, but we lose so much. The context, references, and verbiage of a speaker are lost. Scrawled notes on paper are rarely, if ever, shared with those who couldn’t make the conference.

Freely available, web-based, text notes persist across time. Those not able to attend can still learn. Those who do attend can reflect and remember. Ultimately, when the conference ends the learning continues. When multiple people publish notes you learn what parts of a talk resonate with whom. You are able to collectively document a shared experience.

In the future I would love to see more people actively documenting conferences. Notes help us move our respective communities forward. With notes speakers can build upon the talks of others rather than reinventing the wheel with each event. Notes help us spread knowledge beyond the few hundred people fortunate enough to attend. With notes we assert control over the ephemerality of conference knowledge.

Landing in NYC


Snapped this while flying in to NYC on Thursday night. Been having a blast at Theorizing the Web.

Write the Docs: Swizec Teller – What I learned writing a lousy tech book

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Swizec wrapped up the second day of talks. He writes code and books. The latter is the story he told.

The publisher found him after Swizec wrote a short blog post about displaying dots through d3.js. About a month after the blog post he got a book proposal via India. That was October of 2012. He quickly read the spec for d3.js and faked his way through an outline. The “good” news was that the publisher liked the outline and signed a contract for the book.

Then came the writing of a book. He outlined this as a 4 step process

  1. Think about it. Decide what you can cover in Chapter 1 that doesn’t require you to say, “This will be explained later.”
  2. Learn about it. Read the API spec, figure it out.
  3. Code it. Prove that you’ve actually learned something; it’s a means of testing your writing.
  4. Write about it. Pull it all together and synthesize the experience.

The nice thing is that writing about something you’ve already learned how to code can be extremely easy. Finishing the book becomes about repeating that cycle for each and every chapter.

After 66 days and 171 hours of writing Swizec had a 179 page book. He was sick of the book by that time but was happy that it was done. Then came the editing. While he was happy with the book the publisher came back with, “We love it!…but not really.” They wanted him to shorten the book by 60 pages. Swizec then rewrote everything. While he didn’t have to make new examples he essentially rewrote every piece. He killed the beautiful turns of phrase, jokes, and other pieces that made writing fun. Throughout the editing process he relied heavily upon On Writing Well.

That was the major rewrite. He then did another minor rewrite of additional typos and fixes. Unfortunately then the technical editors got back with their feedback and suggested even further rewrites to the technical examples in the book. Luckily by this point publication was so soon he refused to do deep structural changes. The book was published in October of 2013, one year after starting. After 12 months and 333 hours it somehow ended up being 194 pages long. It shipped on his birthday.

After publication he didn’t get much information, just a quarterly report of sales and royalties. It’s sold about 1,000 copies so far.

Overall Swizec learned that publishers are difficult to work with and that books can be the best way to learn a piece of software. Writing a book is a hard, humbling slog and is truly a fight.

Write the Docs: Mikey Ariel – Your Personal Tech-Writing Agile Manifesto

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Mikey’s talk took the concepts of agile software development and focused on how they can apply to writing. She works at Red Hat and lives in the Czech Republic. In a previous role she was a scrum master in an agile environment.

Mikey started her talk with a brief background or history of agile development. Traditionally software development relied upon a waterfall process. While this process worked well for physical factory production it didn’t work as well for digital software. All of a sudden we didn’t have time any more. The delivery time for software had to be faster and faster; users are impatient. The shift was toward more incremental, iterative development. This led to agile. Agile goes through the design, code, test, ship process multiple times rather than in one monolithic cycle. The key is to be flexible and adapt to whatever environment you work within. There are 4 key principles to agile development:

  1. Individuals and interactions over processes and tools. While there is value in processes and tools the people you work with come first.
  2. Working software over comprehensive documentation. Docs are still okay, though, you just want to ensure they’re granular and not monolithic.
  3. Customer collaboration over contract negotiation. As a writer you want to hear what the customer has to say and make docs a first class citizen in the software.
  4. Responding to change over following a plan. The key is to stay aware of what’s coming down the line and shipping every day in the code.

The flexibility in this is how agile relates to writing docs. As a writer you’re thrown in to an environment that you must adapt to. Staying ahead of the code helps ensure your docs never get swamped by current releases.

Write the Docs: Kristof Van Tomme – Keeping trust: Testing documentation as part of a continuous integration process

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Kristof, who helped make this conference happen, is an evangelist in the Drupal community. His talk focused on documentation in a post-agile world. Given the more hectic nature of agile software development ensuring that your documentation is up to date is quite difficult. You end up maintaining multiple versions of documents, sometimes writing docs for features which haven’t yet shipped or even been finished in code. You know the docs will fail at some point, the question is when.

The trick, though, is that developers already solved these complexities in the shift to agile development. On the software side developers have automated aspects of QA in order to speed up deployment. Kristof believes we can take that same mindset to docs. You can do this by either merging docs in to tests or embedding tests in to docs. Both are difficult.

In DITA documentation is broken up in to references, tasks, and concepts. References are written in code or extracted from from code. Common examples are documentation around API functions; these become easy to test. Tasks let you document automated execution in your project. Concepts let you address places where terminology may change between two versions of your code. Using embedded RDFa or a thesaurus extractor you could try and ensure your code and documentation agree.

Kristof also talked a bit about building the ultimate user guide to the internet. This stems from his project WalkHub. The concept is that online tools and sites often require us to absorb too much information. Luckily, though, there is a shortcut; it’s about cognitive load reduction. People have a limited amount of working memory and if you dump too much information on them they’ll overload.

Write the Docs: Fintan Bolton – The community wrote my docs!

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Fintan kicked off the longer talks after lightning talks. He works as a writer at Red Hat and focused on where community documentation meets product documentation. His talk explored whether a community could write your proper, official documentation.

As writers we never have enough time to pursue all the projects we want to accomplish. The community Fintan works with has written about 1,000 pages of the 6,000 total pages of documentation. While the community’s documentation lives in a Confluence Wiki the official Red Hat documentation needs to live in DocBook. The community wiki gives a low barrier to contributing an pairs instant publication with plain text editing. DocBook, on the other hand, is more complex to edit but presents good formats for archiving docs and has a rich markup vocabulary.

They rely upon a commercial tool to convert the Confluence wiki information to DocBook. Simply converting the content, though, isn’t enough. There’s still a distinction between community documentation and corporate documentation. What they run in to in this process is:

  • Variable quality in community docs. There might be different formatting, styles, or more.
  • Community documentation frequently has different versioning.
  • Community documentation may have inappropriate content, links, and more. Things like untested features you’re not yet supporting.

Given that, Red Hat goes through a process for synchronizing their community and product docs. They use a separate repository for each and maintain a series of snapshots for both sets. These are stored in their version control system. Ideally these sets stay close to each other. In reality, though, after a couple releases the two sets diverge quite a bit.

What they’ve done is simply compare the community docs with an automated diff tool and then merge those changes in to the current product docs. It trades a bit of manual labor for less divergent doc sets.

Ultimately bringing in community documentation from open source projects is tough, but worth it. The different formats, tone, and necessary information can take time to sort out but eventually gives you a much stronger base to work from.

Write the Docs: Elizabeth Urello – Blogging as Non-Traditional Support Documentation

I’m at Write the Docs today in Budapest and will be post­ing notes from ses­sions through­out the day. These are all posted right after a talk fin­ishes so they’re rough around the edges.

Elizabeth wrapped up the talks before lunch in talking about blogging as non-traditional support docs. For WordPress.com the traditional documentation exists as a sprawling support site with hundreds of docs. The support staff primarily writes and maintains the docs.

Blogs help document things for readers in a few ways. First, they let readers subscribe and provide an incremental introduction to various topics. Email updates are occasional prompts to keep learning for new users.

Second, it turns documentation in to conversation. Readers can comment on the posts and interact directly with staff. That feedback loop can help guide future iterations.

Also, blogs have authors. Users know who the writer of a document is. It can help create an ongoing relationship between staff and users that’s based around creativity and proactive support rather than merely troubleshooting. That aspect can also expand the pool of people writing your docs. People have a better frame of reference for how to write a blog post than a support doc. At WordPress.com this means that the person launching a new feature or theme writes the initial support doc as well as the announcement post.

Blogs also give you a fresh start to your documentation. It’s easier to start a new blog than to overhaul an existing support site which means experimentation comes more easily. What you learn from blogging can then be applied to the documentation.

The two main ways this happens is through the main News Blog and through the Daily Post. The News Blog focuses on new feature announcements, company activity, and highlighting less popular or well known features. The Daily Post hosts weekly writing and photo challenges as well as focusing on more task-based instruction. In the last couple of months the Editorial Team has also put together a couple ebooks that focus on things like Photography 101. The material comes straight from blog posts over the months and acts as a great resource for new users.

An example Elizabeth highlighted was the Zero to Hero program started in January. Alongside each challenge there was an open forum thread for questions and comments. By the end of the month participants published 48 times as often as a randomly selected control group.