Stack Exchange Network

Stack Exchange network consists of 175 Q&A communities including Stack Overflow, the largest, most trusted online community for developers to learn, share their knowledge, and build their careers.

Visit Stack Exchange
70

A few additional options: Introduce a named person (perhaps fictional), and use that person's name. "Terry wants to create an account. She chooses a password and types it into the text box. No, wait, Terry is a man. I think. Damn, that's a lousy example. Pat wants to create an account. Um, I mean Chris. No, wait. Maybe Dale. Er..." Use the imperative mood, ...


67

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 ...


58

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 ...


45

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 ...


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, ...


33

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 ...


32

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 ...


31

There is not really much you can do in a situation like this other than to clearly alert the reader to the situation up front. If there is no way to verify the next five actions until you have completed all of them, put a warning in big shiny letters saying: WARNING: The next five steps must all be completed correctly before you can test the result. ...


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 ...


30

The typical user of technical communication is in a hurry and in a bad mood. They were working along trying to get a job done so they could go home and have supper with the kids then something broke or refused to work the way they thought it should, or a part would not go on properly, or a bug appeared out of nowhere, or the whole system quit working and ...


29

I think that there is a very strong case to be made that this distinction between marketing voice and tech comm voice should be avoided entirely. There are two main reasons for this: In ancient times, when tech comm and marketing were delivered on paper, each came to the customer at a different time and through a different channel. Generally they were done ...


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 ...


25

They/their can be used in a singular context The user chooses a password, and then they type the password in to the text box


24

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


23

The number one thing that you have to realize about technical writing is that people do not read it for its own sake. They read it because they are trying to do something and they need more information. The writing does not need to engage or entertain because the reader is already engaged with the task. It is their engagement with the task and their need for ...


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

I wrote a whole book on this subject. It is called Every Page is Page One: Topic Based Writing for Technical Communication and the Web. In it I look at the research on how people use technical information and how the web changes how we use information generally and come up with seven principles for topic design. One of the things I looked at in depth when ...


19

Very few use he/she. In academia, there is currently a movement toward using the feminine pronoun at all times. That said, it is far more common (and less remarkable) to alternate pronouns as you suggested. As long as you stick with the same pronoun per example you'll be technically correct, although it is increasingly un-PC to use only male pronouns. Until ...


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

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), ...


19

This is essentially a business problem, which is not to say it is off topic, because technical writers exist to solve business problems. But it is not a problem the writer should try to solve on their own. You have to get guidance from the product manager. However, there is a very good chance that the product manager has not thought this through, so you ...


19

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 ...


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 ...


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