71 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 ...
user avatar
  • 823
59 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 ...
user avatar
45 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. "...
user avatar
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 ...
user avatar
  • 511
35 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 ...
user avatar
  • 351
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 ...
user avatar
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 ...
user avatar
  • 92.1k
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 ...
user avatar
  • 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 ...
user avatar
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.
user avatar
23 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 ...
user avatar
  • 530
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 ...
user avatar
20 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 ...
user avatar
20 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 ...
user avatar
  • 606
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 ...
user avatar
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 ...
user avatar
  • 92.1k
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 ...
user avatar
  • 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 ...
user avatar
16 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 ...
user avatar
  • 606
15 votes
Accepted

Should technical writers illustrate their own documents?

A technical author should always know what illustration would work best at which point in their document. However, it isn't always necessary to prepare the illustrations yourself. For the documents ...
user avatar
  • 1,245
15 votes

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

Don't make your program make a mountain out of a molehill If I see a program show an error message with an exclamation mark at the end, I am either going to assume that something is seriously wrong, ...
user avatar
  • 321

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