11

A recent SO blog-post pointed out a new thing I had missed. Apparently StackOverflow is getting into the documentation business.

https://meta.stackoverflow.com/questions/303865/warlords-of-documentation-a-proposed-expansion-of-stack-overflow

A politely phrased RTFM is a common reply to questions around here, so I'm wondering if perhaps this is a feature the ServerFault community might be interested in as well. We have opinions, and this would allow us to document those best-practices.

Canonical Questions with Canonical Answers

We have a lot of questions with extremely well thought out answers, and are regularly maintained. The 'documentation' could be a very handy supplement to these questions.

Show the right way, as an example to others

In addition to posting the skulls of bad config on the castle ramparts, this would allow us to show examples of what right looks like. Such as a fully commented config-file that explains the why of each line.

The down-side of this is one SO gets as well. Demands to produce step-by-step, click-by-click, keystroke-by-keystroke procedures for doing a thing. And getting ongoing questions when that thing doesn't work exactly right. The concept of 'Documentation' isn't yet evolved enough to have a clear answer for dealing with challenges to the doc, so we still need to see what they come up with.

So yes, it is not a clear win. Thus, the question here.

Disclaimer: I have no earthly clue if this is something we could possibly get in on, but I think it is worth the discussion.

4
  • 4
    It could be an interesting idea but I'm unconvinced as to SO's ability to execute...
    – Rob Moir
    Sep 17, 2015 at 20:00
  • 8
    As is frequently lamented, no one who needs to ever reads anything. We have a huge body of knowledge already but somehow most of the people who ask questions manage to miss it completely. It'll just be a waste of people's time.
    – user9517
    Sep 17, 2015 at 22:03
  • 3
    it is quite hard to find the canonical questions, so maybe we want to start with getting them somewhere easier to find (no idea how though)
    – Dennis Nolte
    Sep 18, 2015 at 8:03
  • 1
    I think SO can do this, their goal is to attract programmers of all skill levels. Our goal is the exact opposite, we only want experienced admins that are looking for knowledge transfer questions, not "how to" or beginner questions.
    – Jim B
    Sep 20, 2015 at 17:34

3 Answers 3

Reset to default
6

As RobM commented, I'm not sure that SO will be able to execute on the vision to get something really solid. On the other hand, I didn't think there was a market to do Q&A better than the hyphen site, so there we are...

Similarly, I share Iain's concerns that the people who really need to read documentation typically don't. On the other hand, if it just gives a better-curated collection of information that we can dupe-close repetitive questions at (I like canonical questions, but I doubt anyone thinks they're a great UX for question-closers), then I'm all for it.

8
  • 1
    Having listened to the recent podcast that talked about documentation I don't get the impression it'll be a close-dupe target. People who come here generally don't want to help themselves they want someone to tell them the answer. Look at the number of simple questions we get about basic vhost/cron/mod_rewrite etc. We and the internet at large have lots of examples of each of these yet people seem to miss them and want a had crafted answer exactly the same as everyone else's because their situation is somehow unique when in reality it's the same.
    – user9517
    Sep 18, 2015 at 7:09
  • 1
    @Iain I am personally grateful for the lazy people who come here, it helps me learn stuff when trying to answer their questions :P
    – Reaces
    Sep 18, 2015 at 7:42
  • 2
    @Reaces Stuff is interesting once, when you learn it. Having to repeat the same lesson over and over again makes it somewhat boring.
    – user9517
    Sep 18, 2015 at 7:47
  • @Iain Which is where new, inexperienced answerers such as myself come in. It's just unfortunate the influx of those seeking free answers greatly exceeds those willing to dig around for answers.
    – Reaces
    Sep 18, 2015 at 7:51
  • 1
    I think my point is clear. Now I think you are being deliberately obtuse.
    – user9517
    Sep 18, 2015 at 7:58
  • 2
    @Reaces Questions should not need to be answered more than once. This is precisely why "Close as duplicate" exists. Server Fault's continual problem is people screaming "It's NOT a duplicate! Your post makes it say foo and I want it to say bar!" - they literally want someone to do their job (or be their free sysadmin) and give them something to cut and paste into the terminal. Learning is not their goal, mashing the button that makes the dialog box go away is. I'd be willing to give SO's new documentation idea a go, but it will definitely not solve that core problem.
    – voretaq7
    Sep 19, 2015 at 4:09
  • 2
    What's "the hyphen site"?
    – 700 Software
    Sep 23, 2015 at 13:19
  • 2
    @GeorgeBailey: Experts Exchange. Joel and Jeff didn't want to refer to it by name, so they called it "the hyphen site" (due to the hyphen being strategically placed to avoid any hint of highly skilled gender reassignment) instead.
    – womble Mod
    Sep 24, 2015 at 2:59
4

Seem like a good way to mix technical blog post with SF.

Some questions can easily be good subject for good documentation.

For SF my concern is that a good documentation usually die in term of age due to lack of article update (to follow new version and such). A practical example is older KB from citrix are now no longer on the Internet. Canonical's answer and question I seen on SF are really generic, thus the one I seen can survive in term of time.

Another aspect is when a lot of documentation will be done, how will we deal with copied content ? I ask as Iam giving some time to a wiki platform, and yes moderation for that is a reality, as copying a good article is a easy way to cheat the point system. Are we ready to add some burden on that level ?

2
  • 3
    Documentation is quite definitely a living document. Programming-oriented examples and such probably age better than, say, Postfix configs. If we go there, we will need to come back as new versions change defaults.
    – sysadmin1138 Mod
    Sep 18, 2015 at 2:00
  • @sysadmin1138 A living document by definition will always other to edit your document. If they reward by point co-editor, then people will do small edit to gain point.. Canonical question already answer those problems IMO. If they dont reward co-editor, then why people will contribute ?
    – yagmoth555 Mod
    Sep 18, 2015 at 12:33
4

I often find official documentation difficult to follow, and generally find myself on "other" sites looking for 'real' examples. I'm sure there are others who are quite comfortable with official docs and I guess it also differs greatly depending on the software in question.

I'd find a living document very helpful for many reasons. I've not asked many questions on SF but of those I have asked a couple of times I've felt that actually all I'm really after is a better example of how something is done, or I've followed a guide without really understanding what I'm doing, because the person writing the guide did understand each step.

Would you still have people asking questions that are 90% the same as something in a document and only 10% unique? Yes, but answers to those questions could increase the quality of the documentation. I might add an answer on topic x, but not have a complete understanding of the topic. Yet I could contribute a good example to the document, or someone else might take my answer and decide it is worthwhile putting in the document.

As for keeping things up to date, perhaps something like tags for version numbers. So you could search application + ver + search term. When a new version is released a tag just gets added to say yes this is still how it works for this version. If it changes, a document is created with the changes and the new version added.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .