72 votes
Accepted

What's the least distracting method to inform editors I'm a woman?

If you are submitting to a professional journal that (like many) puts a short blurb about the author(s) somewhere in the article or journal, you could provide a suggested blurb and ensure that there ...
  • 829
60 votes

What's the least distracting method to inform editors I'm a woman?

As a person of color, I've sometimes had a version of the same dilemma. Is there a professional organization for people of your gender and expertise? If so, you could join the organization, and then ...
  • 56.2k
46 votes
Accepted

When writing an error prompt, should we end the sentence with a exclamation mark or a dot?

In a technical manual or documentation or anything similar, you wouldn't put emotion into the text. The only reasons to use an exclamation point are to convey strong emotion or a serious warning. "...
44 votes

Is there a hemisphere-neutral way of specifying a season?

In technical writing it is important to be precise. If you want to state something, it should generally be stated in the clearest language possible. In a comment you say: I very specifically need ...
  • 521
36 votes

What's the least distracting method to inform editors I'm a woman?

I also have a confusing first name. When I want to clarify, I sign email as "Firstname Lastname (Ms.)". That conveys my gender as effectively as "Ms. Firstname Lastname", but by putting the title at ...
  • 361
33 votes

What's the least distracting method to inform editors I'm a woman?

I once saw someone in your situation address the problem by adding a (gendered) middle name to signatures. This could either be your real middle name if you have one, or a nickname that you're ...
32 votes
Accepted

In academic writing why do some recommend to avoid "announcing" the topic?

In this answer, I am going to explain to you why you shouldn't announce what you are about to write anyway. It is boring and redundant and a waste of real estate on the page. Start with a claim, or ...
  • 97k
30 votes

Can basic grammar rules be skipped when writing text for machine safety labels?

I really like this question. I cringe to say it, but I somewhat agree about breaking grammar rules in the interest of safety. I frequently write technical emails/IT system announcements that are ...
  • 1,574
30 votes

Should software product release notes be in marketing voice or technical voice? (software documentation)

Release notes should describe what changed as seen by the users. That doesn't necessarily mean "all the gory technical details", though; as with other technical writing, you want to tell the user ...
24 votes

What's the least distracting method to inform editors I'm a woman?

Use a courtesy title which reflects your gender. Sign your submission as "Ms. Morgan Meredith." Subtle but unambiguous.
24 votes

When writing an error prompt, should we end the sentence with a exclamation mark or a dot?

No, you don't need an exclamation mark. Particularly in English. Nor ellipsis (...) or anything special. It's a simple statement in every sense. In fact, if it's displayed in a standalone box, you ...
  • 540
24 votes
Accepted

Which is more readable - array of ints or int array?

They both have subtly different connotations. An array of integers gives the connotation of an array filled with or containing integers. An integer array gives the connotation of an array that is for ...
22 votes
Accepted

Can basic grammar rules be skipped when writing text for machine safety labels?

Of course you can't just ignore all basic grammar rules. For example, writing: Not cover the opening machines power be while do. obviously makes no sense to anyone, even though it's got all the ...
21 votes
Accepted

When documenting Python, when should I use docstrings and when should I use comments?

PEP 8 -- Style Guide for Python Code categories comments and document strings (a.k.a. docstrings) under comments sections. Comments Block Comments Inline Comments Documentation Strings Block ...
21 votes

Does DRY (Don't Repeat Yourself) Apply to Documentation?

The more your documentation is aimed at people reading it like a book the less you should repeat yourself. The more your documentation is a look at this one page read it put it away the more you ...
  • 626
19 votes

Where do I start with C++ documentation?

What you write depends on your audience. API reference documentation -- the output of tool- like Doxygen -- is usually for the users of that API. Such externally-facing documentation focuses on the ...
19 votes
Accepted

Preferred word for "preferred", "target", "chosen" in end user support documentation

One possibility is to not use the adjective: "Select a printer". Another is to use the adjective appropriate to the action: Sometimes you mean "Select a disk", sometimes (like for formatting) you ...
  • 97k
17 votes
Accepted

Should IKEA assembly instructions be used as positive examples to train technical writers?

I think they are great examples—if your use case matches. They never explain two things differently across all their products. Take the world's most sold book case, that Billy you referenced. It has ...
  • 626
16 votes

Can basic grammar rules be skipped when writing text for machine safety labels?

The label should be as short as possible without creating ambiguity. In many workplaces, the employer is required (OSHA, ISO, FDA, etc.) to train anyone who would be working in a particular area with ...
  • 291
16 votes
Accepted

Instruction manuals: should the end-user be addressed directly (passive vs imperative)?

Use direct, simple, clear, imperative instructions. Passive voice and subjunctive make your language unclear and complicated for an international audience. Luckily in this respect there is no ...

Only top scored, non community-wiki answers of a minimum length are eligible