Hot answers tagged technical-writing
18
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, ...
15
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
...
12
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 ...
10
It is one of the things that irritates me, the fact that users are so often considered "dumb". They are not. In many cases, they are more intelligent that the designers, it just may be that their skills are different.
It is better to say that the users are not familiar with the technical issues involved. Or that the best UX solution is to make the front end ...
9
There's a problem here: Saying something like, "users are stupid," makes you look ignorant.
As other have said, the fault isn't always with the user; sometimes, a product is poorly designed. And, even though some users will search frantically for the "ANY" key, many other users are proficient, not dumb.
I realize you mean the statement tongue-in-cheek, but ...
7
Nothing to do with intelligence
I would instead write something like this.
You should try to make it obvious how to use your app, recognizing
that it is there to serve the user. Imagine a brain
surgeon trying to use Skype to consult with a colleague. This user has
limited time and attention. She does not want to
spend 30 seconds figuring out ...
6
That is a marketing ploy that they are using to claim that they provide royalties that might be considered to be higher than the average royalties paid by other publishers. Considering that these royalties are usually pretty meager at best anyway, that probably isn't much of a claim!
As far as determining what the industry average really is, it would ...
6
Contractions are, by their very nature, informal, as they tend to be more frequently used for speech than writing. However, you don't necessarily always have to avoid them: although the APA Style Guide recommends avoiding them for academic writing, other style guides, e.g. Chicago Manual of Style, recommend using them, for when "used thoughtfully, ...
6
No, it's not okay. Why not simply give your advice as something to make an app great because its visual appeal and intuitiveness make it easy to use? As someone with some recent experience in an HCI/UI design group, as well as lifelong experience as a user of technology, I think it is the developer's job to make a great UI so the user can spend less time ...
5
I sympathize with the sentiment, but no, you can't use "black humor" and "shop talk" in a book like that. Such comments have to be kept in-house and preferably not written down. We all complain about horrible clients and idiots at the DMV and so on, but you shouldn't actually codify that into written advice.
Users as a group are too diverse to call them all ...
5
I think you can use "click" with relative impunity. Even someone on a tablet or smartphone knows that "click" equates to "tap" with a touch interface. If you really feel strongly about it, you can say "Click or tap" or "Click/tap," but ask around to make sure it doesn't sound clunky.
I agree that "select" is the right word for "choose one or more of these ...
5
If you want to be cool and scientific, explaining a process, do it in third person. "The subject is, the subject feels". This is the professional mode, very impartial but neither the easies to write nor the easiest to understand.
If that's a colleague though, feel free to use whatever you feel like, First person, second, third, first introducing the actors: ...
5
If you want your tasks to have multiple endpoints, then you need to have an EXPLICIT branching point.
1 Open Gmail
2 Click on Contacts
3 Do you want to view (a) a single contact or (b) all contacts.
4a To view a single contact, click on the name
4b To view all the contacts, click the "contacts" link.
4
Oh no, not another C# book ;)
Joking aside and to your question: Think about what was "dawning" on you and think about your audience.
If you want to write a book for idiots, save your time, idiots don't read books. So do you think your readers are idiots?
You are reading this, so I guess your answer was "No!". Then don't treat them like they were. No ...
4
That's how I'd do it. I'd capitalize it even if I were referring to someone else's book:
For those who are new to programming, I strongly suggest reading through Chapters 3 and 4. For those who are more advanced but need to brush up on databases, I suggest Robert Foo's How I Learned to Stop Worrying and Love Relational Databases, Chapters 4 and 7.
4
Focus on your main goal:
It should be readable and intuitive
The other two goals make your life easier, but not necessarily the lives of your readers. Your readers come first.
So screenshots of a directory structure would be easy to comprehend. But if you have stress and have to finish the book because of some deadline, what will suffer most? Yes, ...
4
I don't think calling users as a general group stupid is appropriate in a development book. It would be appropriate in places where developers or customer-service reps vent to each other and try to top each other's "who's had to help the biggest idiot?" stories.
It's also not really relevant to the point you're making. Users might have any number of ...
3
There are three things you need to publish such a book:
Mastery of the subject matter.
The ability to write well, in an engaging, informative style and samples to prove that.
A publisher.
The usual practice is to get an idea for a book that has not been covered to death, write a proposal, and submit it to various publishers along with samples of your ...
3
There are a few tech writing blogs and forums that I like. Joining STC is useful, though it costs $195 a year ($160 if you graduated within the last three years). Membership includes access to both their publications. Intercom has a lot of best practices articles and information about new tools, while Technical Communications is their academic journal.
I'd ...
3
I would say that yes, it is acceptable. Obviously it's an oversimplification, and the average user of any particular Android app will be approximately as intelligent as the average human being. However, if you don't feel that you need to go into the rationale behind Don't Make Me Think simple design philosophies, then you may find "users are stupid" to be an ...
3
I do something similar to your ASCII implementation, but instead of an ASCII block I use compact bulleted lists (with sub-lists). (File/directory names are still styled as they would be in running text.) In addition to conveying the structure, this also gives me a handy place to add explanations where needed, which is particularly important when (from the ...
3
If I'm understanding you correctly, I think what you want are case studies to demonstrate your points.
So you put forth one of your arguments — "switching to the individual bucket version reduces problems A, B, and C" — and then you put in a section with an actual real-life example:
Case Study: Acme Widget Coders Amalgamated
AWCA had been ...
3
Well it is clearly an insult. So, if your book is supposed to have users as a target group, then it might not be wise to insult them.
Also, to conclude from someone's trouble finding an icon somewhere (or similar struggles) that this person would be stupid... well, this does not make you look so bright either (if I may say so.).
You could, however, make ...
3
It's completely your decision, and the decision you make will help contribute to your writing style (which is why some writers are successful and some are not). So, therefore, you're asking for an opinion on writing styles and what decision we would make.
Mine is that you don't resort to this approach of establishing a light-hearted way of making the point ...
3
I use mind mapping software (Freemind, Freeplane) to organize all of my writing projects. Blocks of text can be imported and then moved around as needed. You get a visual representation of your outline, as well as quick access to any part of your content. Areas that are completed, need content, or are under review are easy to mark with visual icons. When ...
3
My first advice: Don't make your readers' eyes bleed.
Imagining several paragraphs with bold, italics, grayed text, whatever, just makes me creep. Trying to keep in mind what which formatting means, makes me cry. I wouldn't stand a page reading that.
Second advice: Don't use experts' diagrams for laymen.
The diagrams Maura links to are incomprehensible ...
3
Well, from my experience, I've always heard that reading helps on improving writing, and that worked for me! I hence would suggest you read a lot. This will help you expand your vocabulary, get more at ease with sentence structures, spelling and grammar and if you read specific things coming from newspapers, magazines and other articles relevant to what you ...
3
Adding to Jerry's answer;
Someone once told me that,
If you're serious about becoming a writer, you should start reading "The New York Times".
Read as many articles as you can every day (I know, you'll probably only be interested in the contents of a handful of them, but, you'll just have to power through!) and you'll soon find yourself looking up ...
3
In addition to reading (as suggested by others), practice writing in contexts that are already available to you. (Starting a blog is good too, but if you can't build a reader base that can be discouraging.) You're a CS major; that presumably means you are designing and implementing software. There is more to software documentation than inline comments in ...
3
@Wilbeibi To improve my writing skills, I join on line writing communities. That way I also learn more about writing by reading others' work. The internet gives me so much advantages because I only need to sit in front of my computer then reach many ways to many spots. Definitely every one has their own unique style for their writing, it is linked to their ...
Only top voted, non community-wiki answers of a minimum length are eligible
