WordPress.org

Ready to get started?Download WordPress

Forums

How about some documentation? (23 posts)

  1. omigosh
    Member
    Posted 6 months ago #

    I've about had it with wasting time trying to get websites done in WordPress. I can't understand why programmers go to the trouble of creating themes and widgets then foisting them upon the WordPress community entirely without any clue as to how they are supposed to work other than the delightful intro remarks like "Solves the Problems of World Peace and Hunger Without Resorting To Any Programming or Work" and then refusing to do anything resembling what they do.

    Sorry for the rant, but I've just blown my Saturday evening wasting time with WordPress. What a useless, stupid, pointless endeavour. Writing your own code is far easier.

  2. cubecolour
    ɹoʇɐɹǝpoɯ
    Posted 6 months ago #

    I have removed the tag you added to this thread. please do not use foul language like that again on these forums. It might be worthwhile to take the time to review the available documentation and existing support threads as part of the process when you choose the free themes and plugins you use, and then use the ones that appear well documented and supported.

  3. omigosh
    Member
    Posted 6 months ago #

    Well, shucks, that is the gosh-darned point, dagnabbit. I golly-gee wish the heck there actually was some documentation to read for goodness sake.

  4. cubecolour
    ɹoʇɐɹǝpoɯ
    Posted 6 months ago #

    I don't think you read my reply properly. There are plenty of well documented and supported themes and plugins.

    Each theme and plugin has documentation and a support forum available from the theme or plugin page on WordPress.org. Some plugins and themes have better documentation and are better supported than others. It is up to a plugin author how much documentation and support they provide. If you are the type of person who does not enjoy working things out for themselves (and there's nothing wrong with that) you would be happier choosing the ones with more comprehensive documentation which are actively supported by the author and peer users. There are plenty of these.

  5. omigosh
    Member
    Posted 6 months ago #

    Really? There are almost no themes or plugins at I'd call well documentated. Take the theme twenty fourteen for example. There is about a page of documentation in the codex and a support forum where people are asking the most basic questions, like how the built-in slider works, which should have been covered by documentation. There are hundreds of plugins with literally no documentation such as Accordion. Many plug ins in WordPress are useful and some themes are inspirational in their design but after spending hours trying to make them work, I've had to look for alternatives. WordPress is supposed to be easy and quick, but I find it frustrating and slow. It's easier to build a straight HTML site in Dreamweaver and add PHP and Jquery where needed. That is regrettable however because you lose the other advantages of WordPress.

  6. Andrew
    Forum Moderator
    Posted 6 months ago #

    To clarify, what you'd call well documented is not referring to the forums?

  7. esmi
    Forum Moderator
    Posted 6 months ago #

    There are hundreds of plugins with literally no documentation such as Accordion

    All plugins hosted on wordpress.org have their own dedicated sub-forum. So you can contact the plugin's developer directly by posting to that forum via the plugin's WPORG page. Ditto for themes.

    So if you do come across poor or otherwise inadequate documentation, it would be helpful if you could relay this to the relevant developer. There isn't a great deal we can do on a general basis.

  8. leejosepho
    Member
    Posted 6 months ago #

    WordPress is supposed to be easy and quick, but I find it frustrating and slow.

    As others have acknowledged in various ways, that can be relative to one's ambitions, expectations, choices and personal abilities. I knew nothing at all about any of this just over a year ago, but I decided to leave the comfort and security of WordPress.com and venture into self-hosting various downloads from WordPress.org while realizing I had much to learn in order to do that with any degree of success. I have occasionally felt your frustration in relation to documentation, but then that frustration has almost always stemmed more from my personal ambitions, expectations, choices and abilities than from author negligence in a setting where most are simply sharing their work rather than trying to satisfy an end consumer or user that might actually do better at WordPress.com.

  9. omigosh
    Member
    Posted 6 months ago #

    Does anyone approve plug-ins or themes, or can develoeprs just add whatever they like to plug in and theme directories? If there is an approval process, it would seem that proper documentation, written to the level of an ordinary users, would be a criterion for being accepted.

    Also, I notice that there is no tab heading in the details section of the plug-in popup that leads to a manual or how-to-use instructions. We can see tabs for reviews, developer info and how to install, but not how it works.

    Simply saying I should write to the developer is unhelpful since most developers don't respond. There are dozens of sites I can list where the developers pages don't exist or where freebie users can't get access.

  10. esmi
    Forum Moderator
    Posted 6 months ago #

    There are both plugin and theme submission guidelines. Both plugins & themes are also reviewed before being added to the relevant repository.

  11. esmi
    Forum Moderator
    Posted 6 months ago #

    Additionally, how you you determine "written to the level of an ordinary users, would be a criterion for being accepted" given that WP's user base ranges from code guru or complete & utter technophobes? and are expert code reviewers really the best people to decide this?

    I notice that there is no tab heading in the details section of the plug-in popup

    You need to raise this with the developer of that plugin. If s/he does not respond, perhaps you should look for another, better supported, plugin.

  12. omigosh
    Member
    Posted 6 months ago #

    Has anyone ever surveyed the users of WordPress to see if they're happy? I am not happy and I imagine there are lots of people at my level who aren't happy either. The solutions are very easy. Is anyone out there listening or are you just going to tell me to talk to the nonresponsive developers again?

  13. esmi
    Forum Moderator
    Posted 6 months ago #

    What exactly do you expect wordpress.org to do?

  14. omigosh
    Member
    Posted 6 months ago #

    There are two things I personally would like wordpress.org to do.

    Change the order of answers to forum queries so that they are ordered by date in descending order so recent discussions are at the top. that way you won't wind up with five-year-old discussions which are often useless.

    Second, when new plugins and themes are submitted, assess them for the detail and level of instructions provided and give them ratings, expressed graphically or with a short blurb.

    This would not be hard to do and I'm willing to volunteer or serve on a committee or whatever it takes.

    I'm not a complete newbie. I find it easier to produce websites on my own using my skills with HTML5 CSS3 and PHP. WordPress is a terrific platform but the lack of organization and documentation of plugins and themes is frustrating and discourages the use of the platform.

  15. esmi
    Forum Moderator
    Posted 6 months ago #

    Change the order of answers to forum queries so that they are ordered by date in descending order so recent discussions are at the top

    Recent discussions are already at the top. All forums here list topics in "date last posted to" order. We cannot, unfortunately, stop people from posting to topics that are months old - although we do try to point them in the right direction when that happens.

    Second, when new plugins and themes are submitted, assess them for the detail and level of instructions provided and give them ratings, expressed graphically or with a short blurb.

    That's not really feasible in the Real World. Apart from the issues of pitching documentation correctly when expert coders are reviewing it, you cannot possibly assess the documentation unless you actually use the plugin/theme under a range of infinitely variable situations.

  16. omigosh
    Member
    Posted 6 months ago #

    So, query the forum for "remove footer" and see which dates come out on top: the oldest ones.

    As for evaluating tools that are submitted, do you mean you actually don't try them out? How else can you evaluate something?

    I sense you are getting defensive because I'm criticizing WordPress. I have seen you on the forums before and have respect for the time and effort it takes. I also think WordPress is a terrific tool but there is a tendency among programmers to talk to themselves, explaining things to people at their level if they explain them at all.

    I think most people who use WordPress are not skilled in this area and the lack of documentation can be discouraging.

  17. esmi
    Forum Moderator
    Posted 6 months ago #

    So, query the forum for "remove footer" and see which dates come out on top: the oldest ones.

    That's the forum search - not the forums themselves. The search is currently provided by Google and we cannot control the ordering of the returned results.

    As for evaluating tools that are submitted, do you mean you actually don't try them out? How else can you evaluate something?

    Submitted themes & plugins are evaluated against the appropriate submission guidelines. If that is something you are interested in, please see them Theme_Review and Plugin submission guidelines. Further evaluation would require using the plugins in multiple real life scenarios over a very extended period of time. As both a theme & plugin developer, I know all too well just how difficult this is and it simply is not realistic to do this on wordpress.org.

    I sense you are getting defensive because I'm criticizing WordPress.

    No. I am simply trying to explain the real situation to you. WordPress, its themes & plugins are developed by a large community of unpaid volunteers. What you seem to be asking for is beyond what could reasonably be asked of these volunteers. It therefore makes sense to discuss any shortcoming in plugin or theme documentation with the plugin or theme developers themselves rather than insisting that the wider community "do something" about it.

  18. omigosh
    Member
    Posted 6 months ago #

    So the result of all this discussion is nothing gets done.

    What I'm asking for (and volunteering to help with) is better organization and better evaluation of plug-ins and themes. This seems like a very reasonable request but you say it can't be done. You can't test drive new plug-ins to see if they work, you can't ask volunteers to evaluate the documentation submitted with new plugins and you can't write your own search queries.

    I'm sure you're a hard-working volunteer but that "can't do" attitude is no help to your organization.

  19. leejosepho
    Member
    Posted 6 months ago #

    ...that "can't do" attitude is no help to your organization.

    The WordPress community is far more of an ad-hoc society than any kind of organization, and it certainly does not have any kind of "can't do" attitude! This same type of discussion questioning the community took place some time ago concerning the WordPress "Security Review Process":
    http://wordpress.org/support/topic/security-review-process?replies=32

  20. esmi
    Forum Moderator
    Posted 6 months ago #

    You can't test drive new plug-ins to see if they work

    As I have explained "test driving" a plugin takes a lot more than just installing, activating and seeing it work. It can takes weeks to run proper tests.

    you can't ask volunteers to evaluate the documentation submitted with new plugins

    Would you be willing to take this on (serious question)?

    you can't write your own search queries

    The Google search was added as a temporary stop gap. Work is ongoing to upgrade the forums but as this is a truly mammoth task, it's going to take time. And patience.

    I see a great deal of you asking other people to do things but nothing of you offering to contribute. So what can you help with?

  21. omigosh
    Member
    Posted 6 months ago #

    you can't ask volunteers to evaluate the documentation submitted with new plugins

    Would you be willing to take this on (serious question)?

    Yes, I'd be glad to review documentation and cajole developers into providing better explanations where they seem to be needed. I've had a look at the Get Involved section but I'm not sure how to proceed.

    Suggestions?

  22. esmi
    Forum Moderator
    Posted 6 months ago #

    You could have a look at joining the WordPress Documentation team. Their primary function is developing documentation for WordPress core but they are also actively developing handbooks to support plugin and theme developers as well.

    I'll also ask around and see if there are any other pre-existing initiatives that might suit.

    Finally, please feel free to pick an existing plugin, review its documentation and pass all of your feedback to the plugin developer.

    If you're looking for a plugin to start with, how about http://wordpress.org/extend/plugins/eshop/ There are around 80 pages of documentation at http://quirm.net/wiki/eshop/ - 99% of which I authored personally - but which have never really been reviewed by anyone outside of the plugin developer & myself. I would be more than happy to have someone else point out any shortcomings.

  23. Chip Bennett
    Theme Review Admin
    Posted 6 months ago #

    First, thank you for taking the time to comment here. As an admin for the Theme Review Team, I am sensitive to end user needs, and ensuring that Themes hosted in the WordPress Theme Directory serve those needs to the greatest extent possible.

    To address some of your issues as they relate specifically to Themes:

    1. The Theme Directory listings are at a bit of a disadvantage as compared to the Plugin Directory listings. With the Plugin Directory listings, Plugin developers are required to include a README file that is compliant with a specific markup standard. The Plugin listing then parses that README file, to give the various headings/tabs that you see (FAQ, screenshots, etc.) in each Plugin's listing. The Theme Directory does not have this same README-parsing functionality, so Theme developers are limited to control over only the Theme description. Fixing this discrepancy is a (very) long-term goal/project of the small (for all practical purposes: one-man) team that maintains the WordPress.org site.

    2. The Theme Review Guidelines require Themes to support core implementation of any integrated features/functions in a Theme. So, for example, if a Theme wants to implement a custom header image feature, or a custom background feature, or navigation menus, then the Theme must use the core implementation of those features, rather than create a redundant implementation of those features. So, for all core-implemented features, users should look first to the Codex for documentation of those features.

    3. The Theme Review Guidelines do require Theme developers to provide documentation for any non-standard feature/functionality of the Theme. So, for example, if a Theme implements a "featured posts" slider, then the Theme must document how that slider works (e.g. using sticky posts, or using a "featured" category or tag, or a "featured" custom post meta key).

    4. But, as mentioned above, there is no user-friendly display of a Theme's README file. Unfortunately, there's simply no way to parse/display them in the Theme's directory listing page.

    5. If you find Themes that don't have non-standard features documented well enough, please post in the Theme's specific support forum.

    6. But always, please keep in mind, the vast majority of people who submit Themes to be included in the Theme directory are submitting free code that they have developed on their own time. Writing user-friendly documentation is a skill; it is hard, and it is time-consuming.

    7. While I do intend to push for Themes to have Plugin readme-standard compliant README files, it would be impractical to try to define some standard of inline documentation, and would incur an incredible burden for an already very busy Theme Review Team.

    Here's my own Theme, Oenology. I consider its documentation to be a feature. I can't tell you how many hours I've spent on documentation alone, and it's still not perfect. I try to provide the same quality of documentation for my Plugins as well - but again, I don't think it's practical to try to require all Plugin and Theme developers to meet some level of quality of documentation.

    Many Plugin/Theme developers are open to contributions to their code. The best places to start inquiries are the Plugin/Theme's specific support forum, or, as is often provided now, the developer's GitHub repository for the Plugin/Theme. Many developers use GitHub as a VCS, and welcome forks/pull requests. I imagine that the vast majority of developers who host their code on GitHub would practically beg for someone to help with their documentation especially.

    If you have input or feedback regarding the Theme Review Guidelines, please feel free to contact the Theme Review Team directly. We always welcome any and all input, feedback, and criticism.

Reply

You must log in to post.

About this Topic

Tags

No tags yet.