(🏠 elijahcaine.me) (🐙 github 🐱) (👔 resume) (📰 feed)

Write the Docs Day 2

Just like yesterday, I spent most of today enjoying some wonderful talks as well as stressing out -- I mean totally not stressing out -- about my own talk.

Write the Docs Staff Picture

The Write the Docs Staff saying thanks.

  • The first talk of the day was titled "Judas Priest Ate My Scrum Master", which has almost nothing to do with Judas Priest or eating or scrum masters; instead it talked about things that are well known issues and a lot of laws (Brooks' Law, Lehmann's Laws, Pareto Principle, Conway's Law, etc) that nobody talks about that much but can be super helpful to consider when working in an industry.
  • The second talk covered different types of user interfaces and what to consider when writing error messages, troubleshooting pages, product tours. It was something I hadn't considered having primarily written command line tools with pretty limited and well established interface guidelines.
  • Then I gave a talk. It was a talk. I'll post a video of it once those get put up online and you can decide if it was good or bad.
  • The talk after mine was a nice history lesson and wanted the audience to reflect on what documentations can learn from documentation practices of the past. The TLDR on that one is that it used to suck to write technical docs even more than it sucks now.
  • Then there were a bunch of lightning talks. One talk from a twitter employee (there's a fun name for them I'm sure) mentioned that gathering metrics are is important because without metrics everything you do is just guess and check.
  • The next talk "MacGyvering your docs" brought up the fact that the best documentation toolchain will (should?) only help existing developers. A better toolchain won't attract new devs. That was something I think a lot of projects can lose sight of.
  • The talk after that covered a team of scientists studying clouds (water clouds not internet clouds) using computer simulations. They wrote and documented a piece of software and they ended up publishing their program's documentation in a scientific journal. It's already been sited and everything. I hadn't even considered that as a possibility (publishing docs as a scientific paper).
  • The next two talks were pretty short (15 minute) talks about putting the data where the users need it and an introduction to screen-casting. The first was good for documenting things like an API and the second was good if I ever need to make a screen-cast. I doubt that will happen, but you never know!
  • The last talk "All roads might not lead to docs" held too main takeaways for me: The quote The Purpose of this document is ________ and the mailchimp voice & tone guide, which is a very good document I suggest you read it (the title is pretty self explanatory I think).

For a full list of talks given at the conference, check out the event's schedule.

The after party ended up happening at two venues since we got pre-maturely kicked out of the first one; we made the best of it and I got to talk to Anna Jaruga (the cloud research scientist) as well as a Mozilla Development Network writer, both very interesting people.