Tag: #technical-writing

Avoid claiming unrealistic time estimates like “5 minutes” for product onboarding or tutorials. Realistic estimates like “a couple hours” are more honest and set appropriate expectations. 2017-03-14

A technique to improve blogging focus by including a justification for each post, referring back to monthly targets. Allows room for off-the-wall posts. 2017-03-01

Avoid using the word “simply” as it can come across as insulting to the reader by implying the task is easy or the reader is stupid. Instead, rephrase to be more objective and avoid comparatives like “simply” or “just.” 2017-02-22

Avoid using ambiguous pronouns like “it” in technical writing. Refer to specific referents explicitly to improve clarity. 2016-11-25

2014-09-13

Documentation often ends up in black holes - internal documents, issue trackers, test cases, conversations, commit messages, and wikis - where it goes unread. Focus on writing documentation that people will actually read, like product names, homepages, and inline help. 2014-08-13