back to article Stack Overflow takes on technical documentation

Stack Overflow, a popular site for developer and IT admin problem solving, is taking on technical documentation, with support from companies including Microsoft, Paypal, Twilio and Dropbox. The Stack Overflow site was created in 2008 by Jeff Atwood and Joel Spolsky, and originally focused only on developer questions. It was …

Silver badge
Thumb Up

Just took a butcher's at the site

It is actually kind of awesome.

2
0

Awesome or not, one can't help but wonder whether or not it'll end up suffering from the same levels of pedantic asshattery that plague SO in general.

2
11
Silver badge

Re: Pedantic Asshattery

Pedantic Asshattery can be a good thing in Documentation, and may even act as a release valve so not as much of it gets on the Q&A section. I would prefer that the documentation is pedantic and correct, especially if the Q&A gives the answer that actually works.

10
0

A lack of pedantic ass-hattery is (IMHO) the main reason that Experts Exchange and others fell in to disuse way before the EE gods decided to make people pay for using it.

Reading long threads of "meee toooo!" and vagueness may give one a sense of accomplishment at eventually finding the answer, but as a developer on a deadline I'll take pedantic asshattery from experts over novices rambling any day.

tl;dr: pedantic ass-hattery is the secret of SO's success.

7
0
Silver badge

"Good documentation is hard, ..."

It certainly is. After you've gone through all the effort, paying close attention to previous documentation as a model and consulting your technical peers, you then have to get it past all the 'stakeholder' mangers, none of whom have shown the slightest interest in it for all the time you've been working on it, even if you begged them to have a quick look to see if it's heading in the right direction.

If there are five stakeholder managers, there will be at least seven different opinions about where you went wrong and how poor the structure is. After that, you'll spend two weeks acting as their typist until a higher level manager demands to know why it isn't ready yet. At that point it will, magically, be 'good enough'.

(There are certain trigger words and phrases that cause me to go on a rant.....)

11
0
Anonymous Coward

Re: "Good documentation is hard, ..."

Ugh. Yes. I love where all the English-as-a-second-or-third-language folks also want to fix the grammar and introduce their own wacky spelling.

I've had a very plain and simple error message turned into indecipherable mumblespeak in less than an hour.

Anon because Uncle Larry's house of used cars and big orange databases knows where I live.

2
0

If [...] vendors use it as an excuse to pull back on their own first-party efforts

then that might be no bad thing for some people. SO can grow as the vendors withdraw their own efforts, only to later buy out each community and bring it all back in-house again...

1
0
JLV
Silver badge

Re: If [...] vendors use it as an excuse to pull back on their own first-party efforts

re. MS's documentation, I think seeing less of their drivel would be a good thing.

I don't know about SQL Server's doc, but a lot of their Windows user doc is godawful. The product is what it is and I can live with it when I have to. But their docs often take incompetence and vagueness to a whole new level. Even while paying lip service to caring via "did you find this helpful?" links.

For the few actually good documentation entries, their value is hamstrung by Windows' frequent terminology and user dialog navigation changes between releases, sometimes even between 8 and 8.1. I.e. the same common problem can be resolved by the same actions in 7, 8 and in 8.1, it's just that they've moved stuff around and relabeled (pointlessly) and didn't bother to update their core documentation.

Documentation and help is not sexy, but it is key to user acceptance. Using CrackBerry as a de-facto help and documentation site certainly didn't do BB10 any favors - it sucks up all the Google searches, but it has an incredibly low S/N ratio. Much like MS' doc.

I also wonder how SO vendor support is going to play out when the docs point out bugs and errors in the products. No, that particular dig is not limited to just MS.

1
0
Thumb Up

Excellent news

Other than the computer itself, Stack Overflow is probably my most used development aid.

If they pull this off with a similar level of accomplishment it'll be good news all round.

3
0
Silver badge

Re: Excellent news

Well, yes... except that it presumably means Microsoft will now abandon all attempt to provide their own documentation, in the same way as they've already handed "support" over to online communities (including Stack Overflow, for developer tools).

It's just a cost-cutting exercise for them.

1
2
Silver badge

May $deity have mercy on our souls.

1
0
Bronze badge

It's all rather depressing really

Microsoft documentation is well-known for being accurately unhelpful.

Linux docs are comprehensively incomprehensible.

MS docs are pedantic and tend to lack context, or spread the knowledge you need over several pages instead of collecting it together in a way that will help you.

Linux docs just tend to list all options alphabetically and go into great detail, often with lots of jargon, instead of concentrating on the relative few that actually matter.

5
0
Silver badge

Re: It's all rather depressing really

Which is why there is a wide range of Linux howtos faqs and manuals alongside the man pages.

Although it would be good if these collections were more integrated and moved to the web from the man commandline

4
1

Re: It's all rather depressing really

> Microsoft documentation is well-known for being accurately unhelpful.

Usually a case of reference documentation is not helpful until you know the basics. Oracle takes this to the maximum: unless you know a lot about the statement already the reference documentation is completely unreadable (often within the first few paragraphs they're talking about edge cases dependent on database version and/or option settings).

3
0
Thumb Up

Re: It's all rather depressing really

It should all be going both ways; for docs/man pages it should be built into the code, like Python does so well. Then you can spit out docs from there into formal man pages, and then web-friendly or PDF docs, all sourced from down below and offered up above. Same thing with the MS docs; curated is okay and will feed SO, and why any SO docs/how2s would make their way into MS 1st party doc systems is beyond me. Better the 1st part feeds SO, and leave it at that. The stuff on SO is hit or miss, and 1st party is always pretty helpful.

This is one of my pet peeves; IT "developers" who get all their ideas from Google searches. There is so much info in man pages, the 1st party official docs, and integrated help from the code itself that you almost never need to do a search first. That's how I can tell a crap-dev from a real-dev; the real ones can figure most stuff out from the software and normal doc systems. Crap-devs go to Google first. Period. And the output they produce is noticeably shittier that someone who can get the shit up and running without mama Google holding their fucking hand. Every. Single. Time. It's probably okay if you are a muggle, or work for a muggle company, like HP or some other boring as shit IT house.

1
4
Bronze badge
Windows

Re: It's all rather depressing really

Have you tried to find any documentation on the NT Kernel Internals?

1
0
Silver badge
Devil

Re: It's all rather depressing really

@dadmin

This isn't an attack on your good self, as much of what you say I agree with, but you used a trigger word that always, I said ALWAYS, gets my spidey senses tingling. You referred to *Real* devs. That's one of my pet peeves and always makes me start paying closer attention to that individual and the work they produce. Those who use the phrase *Real Programmer/Developer* always consider themselves to be in that category. Real Programmers always want to use C++ for absolutely everything they produce, that or something utterly esoteric that no one else has ever heard of. Real programmers always take longer to produce finished work, often because they insist on doing everything in C++. Real programmers get pissed off doing piddly little GUI jobs - if it isn't games or some complex technical library or kernel coding then it isn't real programming. Real programmers delight in using obscure little tricks that reduce 10 lines of code to less than 3 and leave everyone else scratching their heads, and they never document that code except to say "A cool little trick!". Real programmers love to denigrate everyone who does anything differently than they do. Real programmers love to denigrate other real programmers too, because they aren't as cool as they are.

I could go on but I'm running out of puff and getting a bit bored now, so I'll just finish with - Real *Real Programmers* never call themselves, or anyone else, *Real Programmers* [Tacit implication - I'm a Real *Real Programmer* but really I'm just a code monkey :-) and I have stuff I should be monkeying around with instead of sitting here griping.]

8
1
Silver badge

Re: It's all rather depressing really

RE: "Have you tried to find any documentation on the NT Kernel Internals?"

I think even Microsoft kernel developers have that problem.

1
0

Re: It's all rather depressing really

"Although it would be good if these collections were more integrated and moved to the web from the man commandline"

http://www.die.net/ is a rather good online index of all these docs.

1
0
JLV
Silver badge

Re: It's all rather depressing really

>Linux docs are comprehensively incomprehensible.

True, but the good thing with command line stuff is that it remains static from release to release. You can put it in a quick text note and paste it in years later, it most likely will work.

My favorite combo is to find a good bit of documentation, let's say on using the arcane find command. Often as not on SO. Very rarely from man pages.

Bookmark it privately on Pinboard and paste in the actual command I used to solve my problem in the Pinboard note area. Later on, you can search on bash, howto tags, look for find and you can see what you did or you can go look at the original url if you're still confused. Way better than using Evernote.

Try doing that quickly with a 3 level deep dialog-based configuration that changes from release to release!

1
0
Go

“I, for one, welcome our new insect overlords”

S.E. is an essential resource for our industry, and while it is not a substitute for actual skill and knowledge, having a place that you can apply technical Google-Fu and a site: tag to has saved me hours of wasted time. Conversely I have consistently had to fight Microsoft's site (and it's search functions) for even basic things like looking up a specific KB or CVE, or a patch by it's _explicit_ name. It's also great that they don't block you out from looking at the replies if your not signed in.

Right now I have a curated archive of links and saved pages that is designed to save me time trying to track down a specific thread or posts later. Need to find that post that contained all six steps to uncrash a WSUS installation that filled up it's data drive? Don't bother looking at Microsoft. Why click through another dozen links trying to google it again. Instead lets tag the MS Docs that are useful in the WSUS article on Stack Whatever they call it and add the relevant advice that if it falls down you may need to uninstall the role, manually delete the WID db file, several registry keys, and the patch archive and reinstall it all from scratch. We have been using forum posts for this for too long.

If SE wants to throw me the tools and space, I will help index and add those things to the relevant article when I ask or answer a question. Hopefully they will have learned the hard lessons from the Wiki space and it's technical and cultural pitfalls though. The Technorati can be just as bad as some of the cult self actualization gurus and conspiracy theorist Wikipedians. In any event it's worth a shot.

2
1

POST COMMENT House rules

Not a member of The Register? Create a new account here.

  • Enter your comment

  • Add an icon

Anonymous cowards cannot choose their icon

Forums

Biting the hand that feeds IT © 1998–2017