Documentation… getting out of control?

Become a codex member and implement some of your own suggestions.

I would… believe me =) But unfortunetly I am still very much learning myself…

samboll, with due respect, I think that the people who write the code should also take the time to document it. It is a very important part of developing any product. A sure sign of headlong (and often ill advised) deveopment is not taking the time to document the resulting product.

I think that the people who write the code should also take the time to document it

of course you do. The wordpress developers apparently disagree with you so I guess what you think is of little consequence.

Its an arguement that is the functional equivalent of my saying that “porn exploits women” (just an example, I dont really think that).

Your answer.. apt to be be something along the lines of “tough crap”.

Well… I will signup, but atm I think there is little I can contribute….

whooami, sorry, but “porn” and “documentation” have nothing to do with each other. You really shouldn’t obsess over me so much.

Reality is I have written code for almost 30 years, and even code I am using for myself is at least passably documented. For a major released product like wordpress, documenting the API and keeping that documentation up to date to match the version is key to avoiding problems in the future.

Sort of like writing a decent FAQ – 50% of the “support” questions that are answered by random people such as yourself could more easily be handled with decent FAQs… but I know it’s way more kewl to write the latest ajax popup flashy winky control panel option setting tool than it is to actually make the product work and the documentation relevant.

It’s just an opinion – and having the API / WordPress documentation written by random people is pretty useful… like wikipedia, the world’s largest source of disinformation.

Reality is I have written code for almost 30 years, and even code I am using for myself is at least passably documented.

I don’t believe you.

Seriously, I’ve been a professional coder for over 10 years now, and actually writing code since I was 8 years old. And *nobody* really writes documentation.

It’s one of the eternal unsolved problems, in point of fact. In fact, coders hate writing documentation so much that they have invented whole systems to let them not have to do it. Javadoc/PHPDoc, etc.. automated documentation systems, basically.

So, I’m sorry that you’re disappointed with the state of the codex, but the fact is that if you’re not part of the solution, then you’re part of the problem. That’s my opinion.

And if you don’t like it, then don’t use it. There’s a dozen CMS systems out there, use those instead. We won’t mind. Remember, this is free software. You’re free to not use it too.

It’s just an opinion – and having the API / WordPress documentation written by random people is pretty useful… like wikipedia, the world’s largest source of disinformation.

And this only invalidates your opinion more and more, in my eyes. Wikipedia is the world’s largest source of factual information. Calling it disinformation when it has been proven to be just as reliable as the Encyclopedia Brittanica really doesn’t help your argument.

Wikis work. This is a proven fact. Rejecting that fact does not make it not true.

Otto, how do you think university professors spot students using the internet for research? If the paper is entirely wrong, the information was probably lifted from wikipedia. ??

I started coding when I was 12. This year I am 44. (yes, I was coding stuff back when punch cards, paper tape, and baudot connectivity was considered top of the line). Ever since there has been space to do it, my code has been commented, even if it is just stuff for myself. If I give anything to anyone else, it is also documented. Documentation is a key component in the process of coding, because without the documentation, end users often cannot extract anywhere near the benefits they could if they understood what the program or system can do.

As for considering me part of the problem, I think you are wrong. I think the problem with the codex is like much of the issue I have with wordpress development as a whole: Done too quickly, with too many new features added when old ones aren’t exactly right, and then failing to document those changes. WordPress isn’t alone on doing this, that is for sure. How many versions in 24 months? The codex won’t keep up with that sort of thing, especially when the functionality of things continues to change.

Are all of your threads destined towards topic drift, chest thumping and long posts?

This isn’t the place for philosophical debates — that’s for your blog. ??

For this topic, at this point in time, it’s really cut and dried: contribute to the docs or not.