Search-first writing for non-writers

Session Audio

Excerpt

Search-first writing makes you think about the structure of your document and product as a series of topics, instead of a big book. The days of linear documentation are over, or at least numbered. Users are much more likely to come to documentation through searches.

As an open source creator, you may not have a writer to help you out with this, so how can you maximize their return on your minimal investment?

Description

Tags and keywords, in their best form, contain words that never appear in your document or your software. They are the words that people are using to look for information. Ideally, you wouldn’t generate these ideas yourself, you would glean them from users who are looking for things. You would find them in failed searches and google queries and stack overflow questions, and you would realize that although you think of this feature as the “queuing engine”, the people on the ground appear to call it the “queue management system”. So when you tag, you would use “queue management system” as one of your terms, and tie it to the queuing engine instructions.

Your tags and folksonomy should also serve to disambiguate conceptual information from instructions. You may know what a webserver is, thankyouverymuch, but need to know how to configure this particular one. The metadata should make it clear which is concept and which is execution.

Attend this talk if you want a quick thumbnail on how to make the casual documentation you do more useful for searches.

Speaking experience

Heidi is a frequent panelist at science fiction and fantasy conventions, especially Wiscon. She has given a shorter version of this presentation at Write The Docs.

Speaker

Biography

Heidi has spent years in the technical communications mines, digging meaning out of words and presenting the polished results to users. She firmly believes that less is more and that no one wants to read documentation, which makes her examine her career choices and avoid wordcount trackers. She has worked in industries such as email security, musical OCR, Medicare billing, and operating systems. No matter where she goes, she still ends up writing the release notes.

Her passions include pseudonymity, the intersection of security and usability, and creating the perfect lemon pound cake. In the evenings she is writing a book on using Agile development methods in making and crafting contexts.

Sessions

Search-first writing makes you think about the structure of your document and product as a series of topics, instead of a big book. The days of linear documentation are over, or at least numbered. Users are much more likely to come to documentation through searches.

As an open source creator, you may not have a writer to help you out with this, so how can you maximize their return on your minimal investment?