73
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 ...
- 839
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.5k
47
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.
"...
- 32.4k
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 ...
- 21.4k
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 ...
- 100k
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 ...
- 21.4k
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 ...
- 1,141
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 ...
- 659
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 ...
- 346
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 ...
- 21.4k
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 ...
- 100k
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 ...
- 554
Only top scored, non community-wiki answers of a minimum length are eligible