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

Write the Docs Day 1

I spent most of today enjoying the Write the Docs talks and (air conditioned) venue. I took some notes.

  • The keynote about the imposter syndrome was very relatable. The coping mechanism of framing goals in "I want to do..." instead of "I want to be..." seems like it could be effective. I liked the quote "Make better mistakes tomorrow".
  • The second talk about naming things was very good and got me to think about the structure of documentation metadata (using labels vs taxonomy vs thesaurus, etc). This will be useful someday I'm sure.
  • The third talk about [emojii] and the use of emoji was [emojii]. I never considered using them before, but I will going forward.
  • The fourth talk mentioned using Selenium to test docs, that just makes sense. It's so obvious I wish it was easier.
  • The API Docs talk mentioned that you should give your user the data they will be working with as a top level priority instead of an after thought. This will definitely be a priority for me. I already try to give plenty of examples (since I speak example natively), but I'll be more Conscience of it.
  • The Design Docs with Disability in Mind was interesting. The big takeaway for me was keeping the elderly in mind.
  • The meta talk about crafting a presentation was delivered very well and mentioned adding contrast slide decks... I should have listened to this advice...
  • The second to the last talk of the day covered the plethora of rules we place on documentation. Having just recently helped established some style guides for the OSL docs I think we did a good job of giving some leeway to the writers. The extreme example of 'Limited rules docs' (e.g., the Python Documentation) does not really work well for the reader in my experience.
  • The final talk by some MDN writers equated docs to a garden. The metaphor worked surprisingly well.

For a full list of the talks and their descriptions, visit the event's schedule.

Day 1 was pretty emojii. We ended the night with emojii at a venue called The Pub. Many conversations and laughs were had. I like this crowd.