5

Disclaimer: I do not speak for any projects. I have helped with the documentation of these two projects, that's all.

  1. PHP has really good documentation, with lots of examples. Maybe some curation would make the notes even better but it's pretty good.
  2. Drupal does lack in documentation here and there that's for sure but now we will need to hunt for bad documentation in two places. I already needed to reject an example which recommended an outdated practice.

While I love SO to pieces, this Documentation idea is really bad, will only cause a ton of duplication and a lot of extra work from already thin resources. Please reconsider or at least allow projects to opt out.

3
  • "...allow projects to opt out" Sounds good at first glance, but what if you have projects which don't have good documentation but want to opt out? At least it should be at the discreetion of the users of SO if they want documentation about that particular project here or not. Jul 25, 2016 at 13:21
  • That's their loss. Better have a few bad projects not have documentation this way than sap scarce resources from good projects.
    – chx
    Jul 25, 2016 at 18:26
  • I was about to post this 'question' myself. I already see it going the wrong way (not DRY). I'd suggest people to contribute documentation to the actual projects (if possible). Like documentation isn't hard enough to maintain already... :)
    – Len
    Oct 25, 2016 at 10:03

2 Answers 2

16

You're using a good example of why Documentation could be a great addition to the Internet.

PHP's manual is largely ok, but decidedly not great. Some areas are hellishly underdocumented.

Most useful (and in some cases, essential) examples and background information linger, written by regular users with no editing rights on the official manual, in the comments section, where no one can order or edit them. (Edit: OK, they have a voting feature now for comments. The fundamental point still stands.) Updates and fixes are made by referring to comments made by others years ago.

For years I've dreamed of a place to collect this information in an ordered form. That's exactly the kind of situation the Documentation feature could help.

will only cause a ton of duplication and a lot of extra work from already thin resources.

I'm pretty sure the vast majority of people who are working on Documentation right now were never going to be the official docs for the platforms they're now documenting on SO.

The Documentation feature is tapping into an entirely new market of free help that official documentation efforts have never managed to reach.

There's a chance this will be something that works alongside official docs, augmenting rather than supplanting or harming them.

Let's give it that chance!

14
  • 8
    I disagree strongly. The PHP documentation is not just largely ok. It's very comprehensive with lots of examples and explanation. I would go so far as to argue that PHP SO docs will never even come close to the quality of the PHP manual due to the way documentation is currently organized. As for the parts that are not yet documented in the PHP manual (yes, they do exist. no, that doesn't make it not great), there is an online editor at edit.php.net where everyone can contribute. So if you are unhappy with parts of the official docs, go there and improve instead.
    – Gordon
    Jul 22, 2016 at 6:23
  • @Gordon wasn't aware of edit.php.net, will check it out. My basic point stands though - there is often vital information and examples in the comments section, which is not a good place for it to be. This is where Documentation could really shine.
    – Pekka
    Jul 22, 2016 at 8:56
  • PHP SO docs will never even come close to the quality of the PHP manual due to the way documentation is currently organized. yeah, the feature is going to need some reworking to work well, I agree - it doesn't feel anywhere as smooth as Q&A yet and there's unsavoury things going on. The feature deserves a chance to outgrow that, though. That it has problems now doesn't negate that a community-curated docs feature that lives alongside the official docs could be highly useful.
    – Pekka
    Jul 22, 2016 at 8:56
  • 2
    @Pekka re your comment to chx: I have provided 2600 answers on SO and am the top all time answerer atm in PHP, so I assume I am one of the people who could/should help with it. But I cannot be bothered to copy my content over, nor can I be bothered to fix all that crap. I tried several times. But it feels like the flood gates for dupes, low quality and plagiarism have been opened.
    – Gordon
    Jul 22, 2016 at 9:09
  • @Gordon yeah, I'm not happy with a lot of what I'm currently seeing there, either, and we'll see whether the moderation tools are up to it. What irks me most is that there is no way to just directly comment... they definitely have a lot of fixing to do here. But, as said, the idea deserves a chance IMO.
    – Pekka
    Jul 22, 2016 at 9:11
  • @Pekka웃 I'm missing comments in a bunch of places, too. Something we'll definitely think about.
    – Jaydles
    Jul 22, 2016 at 12:41
  • > That it has problems now doesn't negate that a community-curated docs feature that lives alongside the official docs could be highly useful. - this is absurd. The community can go edit.php.net and contribute documentation to their heart's content. There's nothing to be gained here. Despite SO censoring my comments and editorializing my title, I stand my ground: this is all a very bad idea.
    – chx
    Jul 22, 2016 at 18:29
  • @chx that one platform may or may not have a workable crowd-editing solution does not make the idea of a documentation platform inherently "absurd." Well, I guess we will see how things play out.
    – Pekka
    Jul 22, 2016 at 18:47
  • Drupal documentation is also editable. Give me a break. Or rather, give me an opt out.
    – chx
    Jul 22, 2016 at 21:57
  • @Gordon I stand by that PHP's docs leave to be desired in some places, but I'm coming around to your view that loads of what Documentation is doing currently is duplicating what is already covered adequately there. meta.stackoverflow.com/questions/329173/…
    – Pekka
    Jul 23, 2016 at 16:55
  • 1
    "I'm pretty sure the vast majority of people who are working on Documentation right now were never going to be the official docs for the platforms they're now documenting on SO." - That part I actually don't buy (yet). That may be just wishful thinking. Jul 25, 2016 at 13:23
  • "I'm pretty sure the vast majority of people who are working on Documentation right now were never going to be the official docs" that's what worries me. I would really like this is true, but right now I only see a lot of people writing "Hello World" in the hope they will be the next Jon Skeet. Jul 25, 2016 at 14:31
  • @Trilarion actually at the moment, my statement is more true than it should be. (Given the quality problems that we have)
    – Pekka
    Jul 25, 2016 at 14:46
  • @Pekka웃 I hope that people contributing now to Documentation at least know of other sources of docs and used them so far. I mean they must have used something as a resource before Documentation existed?? Jul 25, 2016 at 15:05
3

If projects already have good documentation, there won't be much incentive to write more. I mean, there might be that guy who will do anything for reputation. But unless other people approve his change requests and upvote his examples, he's not going to get what he wants. The way projects opt out of Documentation is by having other resources that make it unnecessary.

I happen to think Perl's documentation is pretty great, but people sometimes have a hard time finding it. (This insight is a few years old, since I formed it participating on Usenet.) So I wrote an introductory topic that points to perldoc. It turns out other other people think a few other topics are needed, but it would be fine if Perl Documentation were to be a single topic linking to better resources.

That said, every documentation has a weakness. If people find ways to fill in gaps, that's a real gain. Maybe people will try and fail. That's not quite so good, but at least you know the existing documentation stands up to the challenge. I think a common problem is terrible documentation that the authors don't know is terrible.

7
  • Also, anything generated on Documentation can be used by the projects in their official docs as long as they provide proper attribution, correct?
    – Pekka
    Jul 22, 2016 at 0:23
  • Correct. That's one of the frequently asked questions from the projects we we showed Documentation too before launch. Jul 22, 2016 at 0:25
  • 4
    "If projects already have good documentation, there won't be much incentive to write more." Actually, those are the ones that have most incentive, since good documentation usually equals many users which equals popularity which equals lots of people that may not have a criteria and want to play the game.
    – Braiam
    Jul 22, 2016 at 0:25
  • Which moves me to the next problem, stuff with below average documentation usually doesn't get enough traction for people to actually go out and write some... and please lets not use PHP, since it existed when it was either PHP or CGI-bin (which was essentially many times worse) so people had to make do with what was available at that time.
    – Braiam
    Jul 22, 2016 at 0:27
  • @Braiam: At some point we'll need to clear out Documentation nobody cares enough about to edit or link to. (Well, not clear out completely, but make clear its not being maintained as a warning to the reader.) Jul 22, 2016 at 1:30
  • You entire first paragraph shows just how completely out of touch it is / you are imo. I'm saying nothing about whether docs are useful or not, but that thing you wrote is like the exact opposite everybody else has seen when the gates were opened.
    – PeeHaa
    Jul 22, 2016 at 7:11
  • 4
    "If projects already have good documentation, there won't be much incentive to write more." Some people might just like to write the second best available documentation because it was them who wrote it. I wouldn't exclude that possibility and with it dangers of fragmentation and duplication. You gain alternatives and you lose focus. The goodness of the outcome is open. Jul 25, 2016 at 13:29

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