Month: April 2014

I didn’t have time:

This actually means, “it wasn’t important enough.” It wasn’t a high priority, fun, distracting, profitable or urgent enough to make it to the top of the list.

The Minimum Wage Worker Strikes Back:

The paradox of poverty is that tomorrow is unpredictable but the future never changes.

Vox is publishing some of its stories and the interviews behind them in parallel:

But the difference really isn’t Chorus. The difference is that Vox is open to experimentation, it demands rapid iteration, and it puts technology-shaping people on par with word-shaping people. The difference is that, in many traditional newsrooms, changing the UI on a page like this one would have taken multiple meetings where the tech side’s knowledge would likely have been undervalued. It’s a corporate ethos and a permission structure that means good ideas don’t have to get bottled up. It’s being the kind of place that would build Chorus in the first place. That is Vox’s edge, and you can’t buy that off the shelf.

How we were fooled into thinking that sexual predators lurk everywhere. A fantastic post from danah boyd about how our beliefs around online dangers diverge from reality. The bits about how this impacts the presence teens are expected to have in public spaces is fascinating to me. The associated book that it’s excerpted from is now at the top of my reading list.

Paper vs digital reading is an exhausted debate:

Ebooks are here to stay because digital is, and quite shortly we’ll stop having this debate about paper vs ebooks because it will no longer make a lot of sense.

Landing in NYC

20140426-092825.jpg

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

Developer to Documentarian. A neat post from Write the Docs co-organizer Troy Howard. In it he covers the four things that make a documentarian distinct from a developer or technical writer.

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.