WordPress.org

Ready to get started?Download WordPress

Forums

[closed] Documentation... getting out of control? (10 posts)

  1. adondai18
    Member
    Posted 6 years ago #

    Hey guys

    I've been learning how to use WordPress for the last few months or so and of course, I'm loving it. In the course of this I've become pretty familiar with the codex and documentation covering WordPress.

    The tutorials and help here are very, very useful, and I've learnt almost everything just from these, not by asking through the forums etc. What I've noticed however is a lot of this documentation starting to degrade... organisation could be better but the biggest thing is that as WordPress development speeds ahead, the codex isn't keeping up and its full of crossings out, 'notes', 'link rot' and out-of-date information.

    Its a good resource, and when I look at the volume of people clammering for assistance in these forumns, making it a little easier to use could make things a lot better for everyone. Just about all the questions people ask are answered in here... its just sometimes a little hard to find.

    :)

  2. Samuel B
    moderator
    Posted 6 years ago #

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

  3. adondai18
    Member
    Posted 6 years ago #

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

  4. rawalex
    Member
    Posted 6 years ago #

    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.

  5. whooami
    Member
    Posted 6 years ago #

    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".

  6. adondai18
    Member
    Posted 6 years ago #

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

  7. rawalex
    Member
    Posted 6 years ago #

    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.

  8. Samuel Wood (Otto)
    Tech Ninja
    Posted 6 years ago #

    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.

  9. rawalex
    Member
    Posted 6 years ago #

    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.

  10. Chris_K
    Member
    Posted 6 years ago #

    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.

Topic Closed

This topic has been closed to new replies.

About this Topic

Tags

No tags yet.