Skip to content

Instantly share code, notes, and snippets.

@ddbeck
Created February 24, 2016 16:50
Show Gist options
  • Save ddbeck/b5c71e19d05390b9518a to your computer and use it in GitHub Desktop.
Save ddbeck/b5c71e19d05390b9518a to your computer and use it in GitHub Desktop.
Write the Docs London 23 February 2016 Notes

Write the Docs London 23 February 2016 Notes

I had some excellent conversations with folks at the Write the Docs London meetup on 23 February 2016. Here's some links to things I remember talking about. —@ddbeck

Podcast recommendations

At dinner we talked a little about podcasts. Here's some podcasts that came up:

  • Slate's Working: interviews with people about their jobs
  • 5by5: a podcast network created by a former technical writer and software developer (and fellow graduate of the fine tech writing program at the University of Central Florida), Dan Benjamin. Lots of different podcasts, mostly conversational format on different topics (the first few episodes of Back to Work are probably a good introduction).
  • Radiolab: an American radio show about science with unusual production and editing.

Markup

The evergreen topic of conversation for writers:

  • reStructuredText and AsciiDoc are two extensible, well-defined, and human-readable markups.
  • I've ranted a few times about Markdown, to anyone who could stand to listen. There is an effort to standardize Markdown, however, called CommonMark, that may be of interest to people who still really want to make documentation with Markdown.

UI conventions

  • A List Apart has had several articles on creating UI style guides or what they've sometimes termed pattern libraries. It's more about visual design on the web, but it might serve as a good model for making UI writing conventions.
  • Coincidentally, A List Apart published yesterday a great two-parter about conversational UIs (i.e., chat bots). We talked a bit about UI voice and I think these articles do a great job of illustrating the relationship between voice and function. Also, I love bots (twitter, chat, you name it), so if you want to talk about bots, hit me up.
  • Finally, there was some talk about tools for making consistent UI text. One particularly nerdy option is gettext, which is intended for l10n/i18n in the Unix world, but you could also use it for single-language consistency purposes. Free, open-source software.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment