Click here to Skip to main content
15,891,621 members

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

Get The Daily Insider direct to your mailbox every day. Subscribe now!

 
GeneralRe: Trump signs executive order to support moon mining, tap asteroid resources Pin
Nelek7-Apr-20 20:13
protectorNelek7-Apr-20 20:13 
NewsHacker brings video to audio cassette tape Pin
Kent Sharkey6-Apr-20 10:01
staffKent Sharkey6-Apr-20 10:01 
GeneralRe: Hacker brings video to audio cassette tape Pin
kalberts6-Apr-20 12:52
kalberts6-Apr-20 12:52 
GeneralRe: Hacker brings video to audio cassette tape Pin
Mark_Wallace6-Apr-20 19:55
Mark_Wallace6-Apr-20 19:55 
GeneralRe: Hacker brings video to audio cassette tape Pin
MadMyche7-Apr-20 2:36
professionalMadMyche7-Apr-20 2:36 
NewsGoogle’s Technical Writing Guide Pin
Kent Sharkey6-Apr-20 8:31
staffKent Sharkey6-Apr-20 8:31 
GeneralRe: Google’s Technical Writing Guide Pin
Greg Utas6-Apr-20 9:07
professionalGreg Utas6-Apr-20 9:07 
GeneralRe: Google’s Technical Writing Guide PinPopular
Mark_Wallace6-Apr-20 9:54
Mark_Wallace6-Apr-20 9:54 
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.
WRONG!

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

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!

GeneralRe: Google’s Technical Writing Guide Pin
CHill607-Apr-20 6:33
mveCHill607-Apr-20 6:33 
GeneralRe: Google’s Technical Writing Guide Pin
Mark_Wallace7-Apr-20 10:05
Mark_Wallace7-Apr-20 10:05 
GeneralRe: Google’s Technical Writing Guide Pin
CHill607-Apr-20 22:14
mveCHill607-Apr-20 22:14 
GeneralRe: Google’s Technical Writing Guide Pin
Nelek7-Apr-20 10:33
protectorNelek7-Apr-20 10:33 
GeneralRe: Google’s Technical Writing Guide Pin
Mark_Wallace7-Apr-20 23:06
Mark_Wallace7-Apr-20 23:06 
NewsWork flow of diagnosing memory performance issues – Part 0 Pin
Kent Sharkey6-Apr-20 8:01
staffKent Sharkey6-Apr-20 8:01 
GeneralRe: Work flow of diagnosing memory performance issues – Part 0 Pin
Mark_Wallace6-Apr-20 20:00
Mark_Wallace6-Apr-20 20:00 
NewsWindows 10 security: Change your password to a PIN, says Microsoft Pin
Kent Sharkey6-Apr-20 8:01
staffKent Sharkey6-Apr-20 8:01 
GeneralRe: Windows 10 security: Change your password to a PIN, says Microsoft PinPopular
Greg Utas6-Apr-20 9:05
professionalGreg Utas6-Apr-20 9:05 
GeneralRe: Windows 10 security: Change your password to a PIN, says Microsoft Pin
Brisingr Aerowing6-Apr-20 12:03
professionalBrisingr Aerowing6-Apr-20 12:03 
GeneralRe: Windows 10 security: Change your password to a PIN, says Microsoft Pin
Mark_Wallace6-Apr-20 20:02
Mark_Wallace6-Apr-20 20:02 
GeneralRe: Windows 10 security: Change your password to a PIN, says Microsoft Pin
David O'Neil6-Apr-20 15:41
professionalDavid O'Neil6-Apr-20 15:41 
GeneralRe: Windows 10 security: Change your password to a PIN, says Microsoft Pin
Dan Neely7-Apr-20 2:25
Dan Neely7-Apr-20 2:25 
GeneralRe: Windows 10 security: Change your password to a PIN, says Microsoft Pin
David O'Neil7-Apr-20 3:52
professionalDavid O'Neil7-Apr-20 3:52 
GeneralRe: Windows 10 security: Change your password to a PIN, says Microsoft Pin
Dan Neely7-Apr-20 4:13
Dan Neely7-Apr-20 4:13 
GeneralRe: Windows 10 security: Change your password to a PIN, says Microsoft Pin
Super Lloyd7-Apr-20 7:11
Super Lloyd7-Apr-20 7:11 
GeneralRe: Windows 10 security: Change your password to a PIN, says Microsoft Pin
Mark_Wallace6-Apr-20 20:07
Mark_Wallace6-Apr-20 20:07 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.