5 ms·

I write the Chrome DevTools docs. "Empathy" is a buzzword in technical writing. Recently I wrote a post [1] imploring technical writers to start recording thems

I write the Chrome DevTools docs. "Empathy" is a buzzword in technical writing. Recently I wrote a post [1] imploring technical writers to start recording themselves as they use documentation. I want to ask you all to consider doing the same and sending me the footage. My main argument is that the best way to actually develop empathy is to watch lots and lots of people actually use documentation to get stuff done. I've already learned a lot just by watching the videos [2] of me build an Angular app. [1] https://kayce.basqu.es/blog/empathy https://kayce.basqu.es/blog/empathy [2] https://www.youtube.com/playlist?list=PL6UItmiYqJhMr_uYG2DkVNW3oUKbLnNJJ https://www.youtube.com/playlist?list=PL6UItmiYqJhMr_uYG2DkV...

ben509 7y ago
> "Empathy" is a buzzword in technical writing. We should use a term that is more clinical in technical writing. The "empathy" we're aiming for is fully understanding the user experience. That is a correct use of the word, but the popular usage is closer to "sympathy," and often people are using it to indicate they care about treating people well in a broader moral sense. (E.g. "do unto others" is morally empathetic.) The difference is that being empathetic morally is an end in itself, whereas being empathetic technically is a means to an end. Dark UI patterns, for example, are very empathetic in the technical sense in that they use understanding of the user to manipulate them.
cheez 7y ago
"I have a problem, ok I will go to the docs and use the search function to find things that may solve the problem" I can't imagine anyone else does anything but this aside from initial foray into a API
- kccqzy 7y ago
  Over-reliance on search may be a sign that you are unfamiliar with the general patterns and background knowledge of how this API is supposed to be used. It is a shortcut, a very useful shortcut nonetheless but it definitely shouldn't be the only way to do things.
  - gridlockd 7y ago
    I would go as far as saying that if your API requires familiarity with "general patterns" and "background knowledge" you probably have done a bad job designing it. Your API has a purpose. It does things. I know what that is, that's why I came here to use your API. I can verbalize what I want your API to do for me, and that is what I will search for. I will not look at your whole documentation, I do not care about your general concepts. All your ideas about architecture and design stand between me and my goal. I want you to apply the principle of least astonishment. If there's something non-obvious that might cause issues, mention it in all the places where it applies. Yes, this goes against your urge to not repeat yourself. Do not give in to these urges. Sometimes people design APIs with great flexibility in mind, requiring you to assemble a great many parts in the right shape to achieve your goal. This is almost certainly not what the user wants. If you intend to design such an API, use the "layered" approach. At the top, there should be the most common functionality, as obvious as possible, with as little configuration as is reasonable. This is the layer that almost everyone will need - and not more. This layer is implemented using the more flexible layer below.
  - cheez 7y ago
    That's sort of presumptuous. For example, I recently needed to create a ORM w/ SQLAlchemy that consisted of animal/{dog,cat} style inheritance. I googled it and came across this wonderfully written page: https://docs.sqlalchemy.org/en/13/orm/inheritance.html https://docs.sqlalchemy.org/en/13/orm/inheritance.html I've been using SQLAlchemy for about 3 years now and I have used it to make my life so easy that I feel bad for other people who struggle with SQL. Does this mean I am not familiar with it or that I know exactly what to look for? Food for thought for you, perhaps.
    - fjp 7y ago
      Not to mention any given user may only use a handful of different aspects of SQLAlchemy, and the documentation is seemingly endless. You could spend a year just reading docs on parts of SQLAlchemy that you'll never use.
- deleted 7y ago
  [deleted]
- jaredsohn 7y ago
  Also can look at a series of searches a person makes and how long they spend on each page. And the things searched for are things that could have perhaps been described better or linked to from the original page.

ben509 7y ago

> "Empathy" is a buzzword in technical writing. We should use a term that is more clinical in technical writing. The "empathy" we're aiming for is fully understanding the user experience. That is a correct use of the word, but the popular usage is closer to "sympathy," and often people are using it to indicate they care about treating people well in a broader moral sense. (E.g. "do unto others" is morally empathetic.) The difference is that being empathetic morally is an end in itself, whereas being empathetic technically is a means to an end. Dark UI patterns, for example, are very empathetic in the technical sense in that they use understanding of the user to manipulate them.

cheez 7y ago

"I have a problem, ok I will go to the docs and use the search function to find things that may solve the problem" I can't imagine anyone else does anything but this aside from initial foray into a API

kccqzy 7y ago
Over-reliance on search may be a sign that you are unfamiliar with the general patterns and background knowledge of how this API is supposed to be used. It is a shortcut, a very useful shortcut nonetheless but it definitely shouldn't be the only way to do things.
- gridlockd 7y ago
  I would go as far as saying that if your API requires familiarity with "general patterns" and "background knowledge" you probably have done a bad job designing it. Your API has a purpose. It does things. I know what that is, that's why I came here to use your API. I can verbalize what I want your API to do for me, and that is what I will search for. I will not look at your whole documentation, I do not care about your general concepts. All your ideas about architecture and design stand between me and my goal. I want you to apply the principle of least astonishment. If there's something non-obvious that might cause issues, mention it in all the places where it applies. Yes, this goes against your urge to not repeat yourself. Do not give in to these urges. Sometimes people design APIs with great flexibility in mind, requiring you to assemble a great many parts in the right shape to achieve your goal. This is almost certainly not what the user wants. If you intend to design such an API, use the "layered" approach. At the top, there should be the most common functionality, as obvious as possible, with as little configuration as is reasonable. This is the layer that almost everyone will need - and not more. This layer is implemented using the more flexible layer below.
- cheez 7y ago
  That's sort of presumptuous. For example, I recently needed to create a ORM w/ SQLAlchemy that consisted of animal/{dog,cat} style inheritance. I googled it and came across this wonderfully written page: https://docs.sqlalchemy.org/en/13/orm/inheritance.html https://docs.sqlalchemy.org/en/13/orm/inheritance.html I've been using SQLAlchemy for about 3 years now and I have used it to make my life so easy that I feel bad for other people who struggle with SQL. Does this mean I am not familiar with it or that I know exactly what to look for? Food for thought for you, perhaps.
  - fjp 7y ago
    Not to mention any given user may only use a handful of different aspects of SQLAlchemy, and the documentation is seemingly endless. You could spend a year just reading docs on parts of SQLAlchemy that you'll never use.
deleted 7y ago
[deleted]
jaredsohn 7y ago
Also can look at a series of searches a person makes and how long they spend on each page. And the things searched for are things that could have perhaps been described better or linked to from the original page.