|
But does it play DooM?
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
|
I’ve written up my advice (sprinkled with great advice from others), but this is way more straightforward nuts-and-bolts training on technical writing. How to write, "this project is cancelled" in a clear and concise manner
|
|
|
|
|
If it's like their C++ coding standard, which forbids exceptions, it should at least be good for some derisive laughter.
|
|
|
|
|
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!
|
|
|
|
|
Quote: If anyone's having trouble documenting things, let me know, and I'll churn out some articles for CP.
Joking apart, I think there is a real need for proper guidance so I'd be interested to read your take on it.
I am sort of smarting a bit at the moment as I've just had a TOR returned by my manager, with some "minor" amendments made to it. These amendments include: taking out the Author, removing the Version numbering, even removing the corporate frontispiece. They have also converted some (I thought very) clear bullet points into some woolly sentences. I want off this project now! 
|
|
|
|
|
CHill60 wrote: These amendments include: taking out the Author, removing the Version numbering, even removing the corporate frontispiece.
If it were only the author and versioning being removed, it would likely be a case of someone wanting to take credit for your work (which happens a lot), but if the branding has been removed, there are two typical reason:
0: A customer is going to put their own branding on it.
1: The company is up for sale, and you're not allowed to see the version with the new branding.
The fact that it's a ToR doc doesn't lend itself to either option, but it perhaps explains why the bullets were converted to normal prose -- bullets are for people who need to follow a process; ToR docs are for people who need to understand the process (which is probably also why they strike you as being wooly).
Just set in you mind that you're writing for someone who isn't experienced in what you do. Too much detail, and their eyes will glaze over, because they're not interested in getting into too much technical detail, at that point, because it's up to them to decide the details, later.
So, even if you think you have the processes nailed, you need to soften the text to suit their role -- they don't need to be told step-by-step what to do, they need to be given enough overviews so that they, in discussions with other involved parties (who also need to provide input, because it affects their workload, too), can decide on steps that work for everyone.
And never get upset if someone changes your text, in a business context, or you'll live a short, unhappy life with a violent heart attack at the end of it.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Good points, thank you. I did say I was interested in your take on it 
|
|
|
|
|
CHill60 wrote: so I'd be interested to read your take on it.
+1
M.D.V. 
If something has a solution... Why do we have to worry about?. If it has no solution... For what reason do we have to worry about?
Help me to understand what I'm saying, and I'll explain it better to you
Rating helpful answers is nice, but saying thanks can be even nicer.
|
|
|
|
|
Nelek wrote: CHill60 wrote: so I'd be interested to read your take on it.
+1
I've responded to CHill, but if you want it too, I'm afraid there will have to be a service charge.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
I wanted to describe what I do to diagnose memory perf issues, or rather the common part of various work flows of doing such diagnostics. I thought the GC saved us from all this? (/sarcasm)
|
|
|
|
|
It's an OK article, but...
... I've forgotten what I was going to say.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
The next version of Windows 10 is expected to arrive this month, or possibly next, and bring with it some changes to security options that will surprise many. Microsoft wants users to stop using passwords and start using PINs. Because six digits beats your correct horse battery staple. Apparently.
|
|
|
|
|
When I restarted Windows today, it suggested that I set up a scheme whereby I could unlock it with a smile [sic] or finger. I have no problem giving them the finger, but I won't take the sticky off my webcam.
|
|
|
|
|
Mine showed me that as well. The only problem being the fact I don’t have a webcam.
What do you get when you cross a joke with a rhetorical question?
The metaphorical solid rear-end expulsions have impacted the metaphorical motorized bladed rotating air movement mechanism.
Do questions with multiple question marks annoy you???
|
|
|
|
|
Brisingr Aerowing wrote: The only problem being the fact I don’t have a webcam.
Cover the entire screen with tape, then.
You'll find it more aesthetically pleasing that way, anyway.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Quote: If someone compromises your Microsoft account password, they can log into your Windows 10 computer from anywhere...
From that part of the article, the MS account password is still being used behind the scenes to log your computer into MS's servers, if you are stupid enough to tie your computer login to a MS account. Unless I missed something. They say to 'never say never,' but I will say I'm never going to take such a step.
|
|
|
|
|
David O'Neil wrote: From that part of the article, the MS account password is still being used behind the scenes to log your computer into MS's servers,
Not quite. As long as you're using the same computer your pin will work without the password being involved. Which of course means that 5 years down the line when the koolaid drinkers buy a new laptop (likely after accidentally dumping a spilling of purple into the keyboard) 99% of them will have no idea that they even have a PW separate from their pin. Which in turn means that the potentially strong password on the account has been reduced to several bits of publicly available information in the form of the reset forms insecurity questions. As effective as screen doors on a submarine. 
Did you ever see history portrayed as an old man with a wise brow and pulseless heart, weighing all things in the balance of reason?
Is not rather the genius of history like an eternal, imploring maiden, full of fire, with a burning heart and flaming soul, humanly warm and humanly beautiful?
--Zachris Topelius
Training a telescope on one’s own belly button will only reveal lint. You like that? You go right on staring at it. I prefer looking at galaxies.
-- Sarah Hoyt
|
|
|
|
|
Also, since people will not want to remember multiple pins, every device they own will have the same pin. So, effectively, a strong password will be replaced by a 6 digit PIN for everything! Microsoft is stuffing themselves with geniuses of the dunce caliber!
"Would you like an icon with that?" 🙄
|
|
|
|
|
Standard MS response. It doesn't matter which of a users PCs is compromised; this is to prevent a hacker from using a stolen pin credential to login as the user on a device owned by the hacker.
Did you ever see history portrayed as an old man with a wise brow and pulseless heart, weighing all things in the balance of reason?
Is not rather the genius of history like an eternal, imploring maiden, full of fire, with a burning heart and flaming soul, humanly warm and humanly beautiful?
--Zachris Topelius
Training a telescope on one’s own belly button will only reveal lint. You like that? You go right on staring at it. I prefer looking at galaxies.
-- Sarah Hoyt
|
|
|
|
|
Error: Pin number already in use! 
|
|
|
|
|
Yet another sad case of the "other logics" that abound in the tech world.
You might think that the word "other", above, could be replaced with a less forgiving adjective, but I couldn't possibly comment.
I wanna be a eunuchs developer! Pass me a bread knife!
|
|
|
|
|
Quote: A point that Microsoft itself drives home in a 2017 posting: "The PIN is tied to the specific device on which it was set up. That PIN is useless to anyone without that specific hardware."
This has got to be the stupidest thing Microsoft has ever tried to push on us. My Windows password is also tied to the machine on which it was set up, and it's a lot more secure than a 4-digit PIN!
The difficult we do right away...
...the impossible takes slightly longer.
|
|
|
|
|
What a crap! I set up my computer at home to automatically log me in at startup. That's just convenient, and if someone steals my computer, he has access to all the crap on it anyway.
Oh sanctissimi Wilhelmus, Theodorus, et Fredericus!
|
|
|
|
|
Think how helpful it could be if an AI assistant guided you in transitioning to a different activity or taking a break, saving you the time and energy spent forging unproductively ahead, continuing to fall behind, or getting further distracted by negative feelings surrounding your progress, or lack thereof. How about now? Now? What about now?
Because we definitely need an AI to tell us when to take breaks
|
|
|
|
|
General 
News 
Suggestion 
Question 
Bug 
Answer 
Joke 
Praise 
Rant 
Admin 
Submit an article or tip
