Questions about Tech Writing

Question Everything / Nullius in verba / Take nobody's word for it

Over at the Writers Q&A site, the moderators have been trying to encourage questions about tech writing. Here are some recent questions I quite liked. (Questions lightly edited and condensed.)

Bullets vs. Numbering: Which to use when?

Question written by Pravesh Parekh

A writer can either choose to use bullets or else stick to conventional (or in certain cases non-conventional) numbering. Are there set guidelines about when to use what? Is the use of numbering preferred over bullets in more professional settings (example, academic writing, technical reports, theses, etc.) or is it left to the choice of the writer?

How to write to accommodate subsequent automatic translation?

Question written by user7610

The texts I am writing will be translated by people who are not experts in the topic and in some cases by a machine with next to none human editing afterwards.

What strategies should I employ to ensure that the final reader will be able to make sense of it?

How can we make compiling release notes less chaotic?

Question written by Monica Cellio

Each of our software releases is accompanied by a set of release notes, which include short descriptions of the following: new features, important or breaking changes to old features, and important bug fixes. New features are pretty easy; people know what’s happening there. Our challenge is with the other two, which boil down to changes.

The writer takes his best stab at it and sends a draft out for review. Iterations happen. […] Now you can almost never take something directly from the bug [report] because, hey, bugs are written by developers speaking to other developers and aren’t meant to be user-facing.

So, with all that as background, my question is: How can we improve our workflow to produce decent release notes more easily, with less back-and-forth and less of a scavenger hunt?

The site also covers fiction, publishing, editing, academic writing, and more. Come check us out!


Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s