Post

Tell us why we want to use your product

Posted Updated
By Jess Chandler 1 min read

tl;dr tell me why your product works for me before telling me how to install it

I’m always struck by how much time I spend evaluating new (to me) products. Here’s how it usually goes:

  • oh, I see a lot of people are talking about Fancy FrameWork or Language or SAAS
  • read a few things
  • seems like Fancy FrameWork or Language or SAAS is at least tangentially related to what I’m doing
  • go to docs…not sure what it does
  • read a few more things
  • Fancy FrameWork or Language or SAAS might be able to [simplify / replace / clean up] some key part of my process
  • go to docs…not sure what it does
  • start the tutorial
  • 4 hours later, tutorial done… nah, I don’t [need / think I’ll use] Fancy FrameWork or Language or SAAS

See what happened up there, reading time, thinking time, considering time, tutorial time.

It’s not okay.

Please, I beg you:

If you are making software, wherever you have the documentation and tutorials, have a bit about what your product does and why I want to spend my time on it. Include:

  • What is the problem that I have that you are solving
  • Where does this product fit in a generic project flow chart
  • What are the competitors (or things I might do instead)
  • What does your product not do
  • Why will I be oh, so happy after I’m using your product?

I know that most of us are sharing open source software (OSS) for the purposes of sharing code that saves us time or brings us joy, and I know we don’t always have time to explain. However, if you have stickers, if you have a website that is not on github, if you have employees…it is unbelieveable to me that I might have to dig to figure out what your product does.

code
development
This post is licensed under CC BY 4.0 by the author.