Making Documentation Better

Uww…don’t go to one of their conferences and say that. :smile:

If time was the deciding variable then anybody could also have written the Linux kernel, git, etc, etc. Everything that gets done gets done in space-time. The quality of whatever actually gets done is determined by the skills of the people trying to do it.

What it generally comes down to is laziness or just plain not having enough time. I know because I almost obsessively document most of my projects just fine, but it becomes easy to get complacent and say “oh I’ll just do that later” and before you know it your project is done and you have no docs.

It’s especially easy to forget to add/update docs when new features are added or things are changed. However the writing itself is pretty straightforward.

The point I’m trying to make is, with a few good PRs Crystal could be pretty thoroughly documented. I think most of the hold off has been waiting for the API to be stable so that things don’t have to be rewritten over and over. I’d be happy to go in myself and write a shit ton of documentation as soon as we’re in the home stretch and v1.0 is on the horizon.

3 Likes

Yes, for the most part I think programmers disdain writing documentation. I do agree in part that experience and skill play a part in this @jzakiya, however in the end it is still related to time. It’s easy to spent loads of time doing what you enjoy and are good at. If you aren’t good at or don’t enjoy writing documentation you won’t want to do it.

I personally enjoy writing good documentation. However, I don’t usually spend too much time on it unless the bit of code is really complicated and I’ll forget it soon, or I’m satisfied that the implementation is complete. So it makes sense to me that sections of the documentation will be sparse until things are solidified. It’s a little annoying from the third party’s perspective, but I appreciate the choice in focusing on the code for now since this is still basically beta software.

Once we reach 1.0 however, I think care should be taken to keep the docs up to date for each subsequent release. Because at that point people will expect (rightfully so I think) production ready code to have production ready documentation.

1 Like