The Insider News
The Insider News is for breaking IT and Software development news. Post your news, your alerts and
your inside scoops. This is an IT news-only forum - all off-topic, non-news posts will be
removed. If you wish to ask a programming question please post it
Get The Daily Insider direct to your mailbox every day. Subscribe
|Ye gods, it's completely useless.
Technically it's not as grammatically incorrect as often as the worse-than-dire "Read this First" technical writing style guide, but it's still garbage that should be avoided.
Their lack of knowledge is shown right from the get-go, with an immediate link on the front page to a page on passive voice, where they open with this:
Quote:Convert passive voice to active voice because active voice is usually clearer.
Technical documents should use passive voice more than almost any other kind of writing, for the simple reason that readers don't give a damn about the "actor", they just need to know what happens.
The example I usually give for this is that "that hole in the road has been fixed" is far preferable to "someone, I know not who, has fixed that hole in the road", because the statement is about the hole, not about the person or people who fixed it.
There is nothing "bold" about active voice; it's just the name of the voice. You could call them banana voice and poms-frites voice, but that wouldn't make one of them yellow, and the other a side dish.
Their explanation, with incorrect statements and bad advice crossed out:
Prefer active voice to passive voice
Use the active voice most of the time. Use the passive voice sparingly. Active voice provides the following advantages:
Most readers mentally convert passive voice to active voice. Why subject your readers to extra processing time? By sticking to active voice, readers can skip the preprocessor stage and go straight to compilation.
Passive voice obfuscates your ideas, turning sentences on their head. Passive voice reports action indirectly.
Some passive voice sentences omit an actor altogether
, which forces the reader to guess the actor's identity.
Active voice is generally shorter than passive voice.
Be bold—be active.
WT-Flying-F has that kind of statement got to do with technical writing, and how do they help someone to learn how to write documentation?
Their examples: The QA team loves ice cream, but their managers prefer sorbet.
Performance metrics are required by the team, though I prefer wild guesses.
When software engineers attempt something new and innovative, a reward should be given.
So yes, they explain what active voice and passive voice are (making the typical mistake of confusing "active voice" with some kind of dynamism), but they completely screw up everything else, by flooding the description with:
• More unnecessary information than useful information
• Useless diagrams
• Pointless verbiage
• Incorrect instructions on how to use the voices
None of which will help people write documentation.
So yeah, it's exactly like a lot of technical documentation, which also fails on the above four points -- but the point of teaching documentation skills is to make the documentation better, not perpetuate cr@p quality levels.
I strongly suggest giving it a miss.
If anyone's having trouble documenting things, let me know, and I'll churn out some articles for CP.
I wanna be a eunuchs developer! Pass me a bread knife!
General News Suggestion Question Bug Answer Joke Praise Rant Admin
Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.