Re:Making world-class docs takes effort
by kaycebasques on Saturday September 04, 2021 @03:44PM
(#28418398)
Wholeheartedly agree with the "your docs features examples" principle. For code/APIs there's really two categories of examples: A) minimal, viable, complete snippets that capture a use case [1] and B) end-to-end working example of core use cases tied together.
The tricky thing about A is actually figuring out the common use cases and then finding the phrasing that your users would say. I was lucky when I worked on the Chrome DevTools docs because I had a huge record of the problems that people actually faced and how they described them: all the google-chrome-devtools questions [2] on Stack Overflow. For smaller products where obviously you won't have an active Stack Oveflow community, a good source of insight is support tickets.
The tricky thing about A is actually figuring out the common use cases and then finding the phrasing that your users would say. I was lucky when I worked on the Chrome DevTools docs because I had a huge record of the problems that people actually faced and how they described them: all the google-chrome-devtools questions [2] on Stack Overflow. For smaller products where obviously you won't have an active Stack Oveflow community, a good source of insight is support tickets.
[1] https://stackoverflow.com/help/minimal-reproducible-example
[2]: https://stackoverflow.com/questions/tagged/google-chrome-dev...