68

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 is at least one feminine pronoun in it somewhere. If they don't, or you don't know, you could say, "in case you need an author's introduction, here is a ...


59

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 sign as follows: Morgan Meredith American Women Tech Writers Association or Morgan Meredith Member, American Women Tech Writers If there is no such ...


44

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 to refer to the timeframe of June-July-August. and since you want a replacement for "Summer 2019" I suggest one of the following: June-August 2019 June, July, ...


44

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. "Your password doesn't meet the criteria" isn't a dangerous situation. There's no need to use anything but a straightforward and calm voice. Just like you would ...


34

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 the end and in parentheses, I don't look like I'm insisting on being addressed by that title. I strongly recommend against putting your photo in your CV, cover ...


33

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 prepared to answer to. If it's your real name, just write it normally: Morgan Ann Meredith If it's a nickname, that is, a name you're happy to have people use ...


33

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 a key observation. Those can be interesting. Don't talk about your paper in your paper, get to your paper! A sentence saying "The goal of this work is XYZ." can ...


30

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 sent out to a large group of non-technical people and I find that if I write the emails using the same language that I'd write in my short stories, or even my ...


29

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 what he needs to know (and maybe a little more), but you don't want to overwhelm him with unneeded details. If there are larger themes in a release, you might ...


24

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


23

If a reader follows a reasonable path1 through your documentation, there should never be a point where he's looking at something incomprehensible. This applies to text, code samples, diagrams...and screen shots. Therefore, unless the structure of your document itself provides this (e.g. through section titles and a consistent format, like in a catalogue), ...


22

No, users are not stupid, it's usually the designers that are. A good UI requires a solid understanding of HCI (Human Computer Interaction) concepts, which range from understanding the target audience, to cognitive load theory. You might be able to get away with "idiot proof", since it's a cliché. Personally I'd avoid painting the users with a broad brush, ...


22

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 could even omit any stop rather than put something unnecessarily flamboyant!!! Warning! This is an example where it might be warranted, but a colon (:) is still ...


20

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 right words (plus or minus a few grammatical suffixes) in there. It's just broken English. But you can totally write, say: Do not open cover while machine ...


20

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 comments generally apply to some (or all) code that follows them and are indented to the same level as that code. Inline comments are unnecessary and in fact ...


19

Shall is still used in software documentation. It was a subject of discussion in my software engineering course and it's also present in field documentation. An example can be found in the Joint Strike Fighter's C++ coding standard. In section 4.2 under Rules on page 11. It specifically defines the following: 4.2.1 Should, Will, and Shall Rules ...


19

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 mean "Select the target disk", sometimes (for installing an OS) "Select the desired boot disk", etc. I wouldn't look for just one word. "Preferred" is sometimes ...


18

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 should repeat yourself. The most concrete example I can think of are aviation emergency checklists. No Co-Pilot is ever required to look anywhere else after he ...


18

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 contracts of the API and how its various components fit together -- how are you supposed to use this collection of classes and functions to write your ...


17

That depends entirely on a number of factors: What's your motivation? (Thanks, Steven Burnap for this one.) Do you just want to get it out there to share your knowledge? Or are you looking to make money (hint - you probably won't make much money off your first book, no matter what route you go)? Dead tree? Ebook? Both? Something else? This is going to ...


16

Short answer: Yes. Slightly longer answer: Yes, a lot! All reading is good, but not all reading is equal. All reading will help you absorb the effective use of written language, will increase your facility with words, will enhance your vocabulary, etc. But if you're really serious, you should spend at least some of your time in conscious, directed ...


16

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 the hazards of the environment and the equipment. The label acts as a reminder (as well as a legal obligation). Everyone in that lab knows lighting a flame ...


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