Leave the sales pitch out of your documentation

When reading software or programming language documentation and how-tos, I find phrases like "Doing X in Bob's Wonder Suite is as simple as clicking Y" rather irksome.

If it's really true that all I need to do is click Y, then it will be pretty clear to me how simple it is, won't it? Just say "To do X, click Y", give it a useful index entry, and have done with it.

Also

Syndicate content

Twitter

  • NYT: "BP Says Crews Make Progress Stemming Oil Leaks." BP also said the leak was 1000 barrels per day. 4 years 14 weeks ago
  • RT @fbjournal: Happy birthday to Pete Seeger! Turns 91 today! 4 years 14 weeks ago
  • New post: Introducing Jeffmenzies.com http://tinyurl.com/2aamtz5 4 years 14 weeks ago
  • Just launched a new #drupal site! http://jeffmenzies.com/ 4 years 14 weeks ago
  • #lazyweb is there a #gitosis config directive for read-only access? "readonly" didn't work. #git 4 years 14 weeks ago

Older

Contact

Andy Chase
(978) 297-6402
andychase [at] gmail.com
GPG/PGP Public Key