[steveklabnik]

Writing documentation is really hard.

It's also hard to get people to contribute to documentation. I had a conversation with someone recently that was frustrated about the Rails documentation: "Here's my blog post about how to do X. Apparently that's what Rails people do rather than write docs." When I asked why they didn't contribute to the docs rather than make Yet Another Blog Post that feeds into the exact problem they were talking about, it just hadn't actually occurred to them. Getting started contributing to a new project is difficult, posting something to your blog is easy.

Most people don't find writing docs to be fun, and Open Source is largely driven around doing what's fun.

It's hard to see the flaws in something you're close to. The people who are closest to a project forget how hard it is to come in from nothing; I had a conversation recently about Hackety Hack where someone was upset it didn't have the ability to make folders and multi-file projects, and when I tried to explain to them that the beginners (children and adults) that I teach actually struggle with things like file management, they were shocked. We all forget just how much we know, because it's easy to us!

Furthermore, there's an incentive for people to write blog posts over contribute to official docs, since then people will link to their blog, with all the benefit that comes along with.

I am not informed on the state of Angular's documentation, and I think Rails has pretty decent docs these days, but there's lots of reasons why docs are often poor in open source projects.

[rdtsc]

> Writing documentation is really hard.

If that is the case then one should wonder about the project itself. If the idea and functionality cannot be easily expressed then one wonders whether that project is worth pursuing.

I stopped being interested in the project. I did look at the source and all the magic going on behind the scenes and didn't like what I saw. It reminds of those large frameworks management would buy for big enterprises and say "just use this, this will be really easy, we'll increase the productivity 100%!".

[sanderjd]

I realized something recently about docs-vs-blogs. An important difference between the two is that official documentation of a project is the place to say "this is how it is done", whereas blogs are a place to say "this is how I do it". If there isn't a consensus on how something should be done, but you think the way you do it is nice, it definitely makes sense to write about that in a blog post, but it only possibly makes sense to propose your way for official documentation.

I think it took all those blog posts to generate all the consensus necessary to make the "pretty decent" (I would say "very good") Rails docs possible.

[pixelcort]

An official blog can be, "This is how it is done, as of the time of posting."

However, then you end up with blog posts like, "here what's new in 3.5", without any documentation for users who never used 3.4 (or 3.3, 3.2...)

[Foxandxss]

You made a good point here. That point of view will prove to be useful to me :)

[regularfry]

My very first PR to the Emberjs project was an improved entry-level tutorial, just to work people past the pain points I'd experienced getting up and running following the then-current getting started guide (which were neither few, nor far between). The initial response? "This would be better as a blog post."

[mgkimsal]

WOW - that's crazy. Thanks for a recent real world example.

[Foxandxss]

I agree with you.

I don't feel I have the experience to write better angular docs. That could be a goal in a future for sure.

Even when I am going to write about things that could be used to improve the official docs, one of my main goals is to answer via blog the questions I see everyday: "Why this doesn't work?", "My directive is not doing what I need", "My service is not updating"...

I think that the documentation itself needs to be done from various angles, and this is one for me.

[pm]

Documentation is hard because those who are documenting assume too much about those who are learning. This concept applies as much to closed source projects as it does to open source projects. It's all a matter of being open to those who are learning, and incorporating what they don't understand.