Hi Jezella,
My usual disclaimer to start - I don't work for StudioPress, so my comments are unofficial in that respect, but I do want to help you resolve this issue on their behalf.
Quote:
|
My grip is that the documentation for this extremely fine product is less than perfect. I will admit that documentation exists but, it is more directed at the not so novice user.
|
Just so we're clear, can you clarify which documentation you're referring to?
As with anything technologically creative, there's always going to be a bit of learning to do; there's no getting around the fact that some basic skills to being able to copy and paste code into theme files and upload them to a site is a requirement to enact customisations. If someone can't, or doesn't want to learn how to
get started, then there is a list of
Theme Customizers at the top of this page.
Quote:
|
I have been on http://designsbynickthegeek.com. We all know that Nick helps a great deal on this forum where I urge anyone having problem with understanding the ins and outs of this absolutely wonderful piece of software to visit Nicks site.
|
I'm not sure if you're contradicting yourself here. Sure, Nick's site is filled with some useful information, but having seen a few of the recent articles where he looks more in-depth at functions with Genesis itself, I'd say that this is precisely the stuff that would *not* be helpful to the novice user that you say we should be targeting.
For a developer, knowing he can pull up all image sizes with genesis_get_image_sizes(), or unregister layouts with genesis_unregister_layouts() (see how these functions document themselves by their name?) might be of interest, but it's well over the top of the novice who just wants to change the style of the read more link, say. For non-novice developers, they can read and understand the code directly and draw their own interpretations of how everything works, just as Nick did to write the articles.
Speaking of which, I've been looking to improve that area (inline documentation) such that the package could be parsed by phpDocumentor or Docblox to extract out the API into external documentation. I've submitted (and had committed) several patches to Genesis which does this, and there's another couple of pick patches to be committed, with one directory of files left to be addressed with patches. In the same vein, we've been looking to pull Genesis up to using the WordPress Code Standards - while not documentation directly, it does make working with Genesis easier if there's a code style consistency with WordPress and related plugins.
With the Trac for Genesis there are at least three tickets that look to make use of the contectual help facility with WP (the Help tab in the top right corner), as this would be an ideal place to include more information that novice users might need. You and I most likely know what changing a certain setting will do, but providing an expanded explanation within the contextual help (or better, linking through to a tutorial) on top of the small description documentation within most meta boxes would be useful in my opinion.
As for the tutorials, this is where I think the bulk of the novice users you think we should be addressing will be most comfortable - see the Developers link at the top of this page. There is currently 119 published articles, with another 10 pending review, and 37 in various stages of being drafted. The code snippets within each article are (or at least should) be written to code standards, and contain inline documentation. Some of the tutorials are little more than "If you want X, then copy and paste this", but others, are less about code syntax and more about explaining *why* something is like it is. Dev.SP is not targeted at "just novices", or "just developers", and you'll find articles aimed at a range of abilities there - as such, you may find some that are below someone's level, while others (which you might not have needed yet, so haven't read or taken notice of) are above their level, which in turn gives a distorted view about the documentation and guidance available.
Finally, we have the support boards themselves - available both for reactively searching and for pro-actively asking new questions. With 332,000+ posts over 63,000+ threads, that's more potential documentation than anyone can manage. Having contributed over 1550 posts to the Thesis boards, and ~2000 posts here, I'm happy to claim that Genesis does this better - threads are limited to one issue per thread, threads are closed when they are dealt with so they don't get polluted by other posters at a later date, and you'll actually StudioPress developers regularly answering posts, unlike at Thesis (at least when I was active there). While this is more the superset of documentation - support - it is yet another means of a user - novice or otherwise - of finding the information they need, which is also the purpose of documentation.
It's widely
acknowledged that StudioPress do pretty well on the documentation / support front compared to others. I'm not saying that the StudioPress-related documentation resources (and that includes the FAQs) are perfect, but I think it's unfair to say that they need to "get their act together" - unless you can provide specific examples that I've not covered?