Updates from January, 2009 Hide threads | Keyboard Shortcuts

  • rip codex. oh, sorry, i meant R.I.P. codex. 

    that girl again 9:26 pm on January 21, 2009 Permalink | Reply

    So, according to Lorelle, Codex is officially dead and being superceded by the WordPress HandBook. Lorelle being Lorelle, she doesn’t admit that Codex is officially dead, but nor does she provide any coherent explanation of how and why two ‘online manuals’ sharing much of the same content can operate side by side. (She can’t seriously believe that Codex will still have a role as ‘a highly technical and historical guide to WordPress’. Firstly, the techies wouldn’t touch Codex with a bargepole, they’re all about the PHPXref. Secondly, a historical online manual is about as much use as a chocolate teapot, otherwise we’d still be directing people to wiki.wordpress.org so they could read about how to get the best out of 1.2.)

    Obviously, switching from mediawiki to XML and SVN is going to effectively debar all but the most dedicated from contributing (for which, read Lorelle and people on the Automattic payroll), but that’s not a bad thing, since a) Codex was not exactly overwhelmed with volunteers, the docs project being a proud part of the long-standing WP tradition of treating volunteers like crap, and b) community-written documentation is next to impossible to keep up-to-date, especially when pursuing a quarterly release schedule. Bringing it under the Automattic umbrella at least means that it will be updated, even if it does constitute another step in the process of taking the community out of wordpress and wordpress away from the community.

    It’s nice that Automattic have decided to focus on documentation this cycle — it was about time — but I can’t help wondering how much cross-referencing will be going on between the new written documentation and the new proprietary traffic-building ad-carrying video stuff…

     

    • Matt A. 9:53 pm on January 21, 2009 Permalink | Reply

      I don’t know. The new handbook doesn’t sound like it’s going to be sufficiently technical to satisfy the needs of this user. I can’t imagine going to that kind of handbook to figure out anything after the first couple days using wordpress.

      Incidentally, I saw a handbook like this in Barnes & Noble last month. I stood in the bookstore and laughed as I read through it; they were charging $15 for the most basic of basic instructions that are available for free online.

    • whatev 1:10 pm on January 22, 2009 Permalink | Reply

      I don’t think the initial Handbook will supplant the Codex, it’ll be the eventual “developer” edition that will do that. In and of itself, having a more structured and centralized repository of “official” documentation isn’t a bad thing; it makes sense for a project of WordPress’s size. The problem is, because resources have been so scattershot for so many years, the “community” has created various solutions to varying degrees of success and I can’t see some long time contribs reacting positively to being pushed out. Had WP had proper official documentation like Django (if they want to copy a model for documentation that addresses regular users and devs, djangobook.com is a far better example than Subversion’s manual…esp. since all the cool kids use Git now anyway), they wouldn’t have the types of conflicts that are sure to happen in the future…

      One thing is for certain, the “the documentation sucks because it is all volunteers” excuse won’t fly anymore. They better be prepared to keep shit accurate and updated.

    • Dr. Mike Wendell 4:25 pm on January 22, 2009 Permalink | Reply

      they were charging $15 for the most basic of basic instructions that are available for free online.

      It’s like the difference between paid software and open source software that’s available for free. Folks think they have to pay for something to get any value out of it.

    • Kissing Bandit 5:17 pm on January 22, 2009 Permalink | Reply

      Or some people appreciate having a hard bound reference manual next to their computer rather than needing to flip back and forth between an free online reference site*.

      You and I may never need to purchase the $15 Dummy’s book because the stuff is all available free at the Codex and we’re willing to do the switch between because, I assume, we have some basic technical knowledge to begin with and aren’t necessarily afraid of breaking something. But the everyman doesn’t exactly see it that way.

      And that brings me to the reason why I believe the WordPress Handbook won’t pan out. The information it will encompass will likely be too basic for anyone who’s been using WordPress for any length of time and for the everyman just starting out, who also has limited technical abilities, the actual writing style will be too complex. Unless they have a truly dedicated team of writers who understand how to write instructions for the layman, it will be a bust. (Just look at the comments on the Codex content, then read the comments left by those people kind enough to write plain English tutorials on their blogs….)

      * Many people don’t like to run prints from their printers unless it’s of an already written/edited book written for the layman and that makes people less inclined to run off copies of the Codex pages since 1) they aren’t written for the layman and often people become confused reading it; 2) many of the Codex pages are incomplete or having errors which are slow to be fixed; and 3) the Codex, in general, is a maze to navigate–who wants to comb through 100 of Lorelle’s blog posts explaining how to use to Codex just to figure out how to write a post on their blog for the first time? It defeats the purpose.

      Climbing off my soapbox now and I apologize if this comment seems in any way incoherent, I’m running on little sleep.

    • Matt A. 6:05 pm on January 22, 2009 Permalink | Reply

      Kissing Bandit is probably right, of course. When I say basic, I mean that there were several pages on how to upload an image onto your blog with step-by-step instructions that included step-by-step screen captures of said instructions.

      It’s the kind of things that people (I would suggest older people) might need for about the first day. It’s like having a guidebook on how to start your car with pictures of a hand inserting the key, then the hand turning the key clockwise. Coming from a nation of capitalists, I’m sure at one point such a thing was published as well.

    • Kissing Bandit 11:39 pm on January 22, 2009 Permalink | Reply

      Well, I just learned yesterday that MB (Mercedes Benz) actually employs a single person who’s only job is to show people how to use their car, including how to open the car door. So, apparently, some people do need that kind of hand holding. (Nothing wrong with that. It’s completely new territory to some people and, as such, people tend to me a more over cautious for fear of making a mistake and irreparably damaging something.)

    • Dr. Mike Wendell 11:41 pm on January 22, 2009 Permalink | Reply

      heh :)

    • Dr. Mike Wendell 3:19 pm on January 23, 2009 Permalink | Reply

      I noted that Lorelle is denying that the codex is going to go away on the mail lists. From the experiences with the theme and plugin depositories as well as the updated FAQ blog over at wp.com, I give it six months.

    • Dr. Mike Wendell 7:20 pm on January 23, 2009 Permalink | Reply

      And of course Lorelle deletes the comment that I left as well as your trackback from this post. It’s interesting that she leaves the multiple splog trackbacks though.

      Considering her behavior lately, it doesn’t surprise me.

    • that girl again 9:32 pm on January 23, 2009 Permalink | Reply

      Well, the codex doesn’t have to go anywhere in the immediate future. Matt can leave it on the wordpress.org servers till it festers into irrelevance, like he did with themes.wordpress.net, and then silently get rid. There is simply no way that a multimillion dollar corporation can continue to delegate documentation to amateurs. It just doesn’t look good.

      Newbies, as I see it, will be well-served by the wordpress.com FAQ, the new HandBook, and the wordpress.tv tutorials. Developers will continue to work stuff out for themselves or ask each other. When I was developing themes a few years back, I found there was more useful information in blogs than in Codex. If somebody writes a half-decent tutorial they’re going to keep it on their own site for the traffic and backlinks, rather than hand it over to Codex and deprive themselves of all rights over its editing, copying and redistribution. (GPL is a lousy licence for creative works, but it is a truly lousy one for documentation.)

    • Barry 1:54 am on January 28, 2009 Permalink | Reply

      amen to @that girl again. The only use I’ve made of the codex in the past 2 years is when I fail miserably to remember the functions that add menu items form within plugins – don’t know why, but I can never remember the order of the variables.

      For everything else I Google and read tutorials on blogs, and my tutorials go straight on my blog.

      Not really had much time for Lorelle, though why are these announcements are made on her blog and not on a “WordPress” blog?

    • andybolton 8:58 pm on February 22, 2009 Permalink | Reply

      Google the overlord … I didn’t realise the saying originated from @that girl again…
      :)

    • Ching 7:31 am on March 3, 2009 Permalink | Reply

      Just dropping by.Btw, you website have great content!

      ______________________________
      Why this one-minute therapy is being suppressed in the U.S. while more than 15,000 European doctors have been using it to heal millions of patients

    • ray 8:34 pm on March 3, 2009 Permalink | Reply

      Yay – more spam!!

  • business v. business. that is how things work now 

    that girl again 12:15 am on April 9, 2008 Permalink | Reply

    Perishable Press on, among other things, what is wrong with the plugin repository, and the quiet removal of the community-maintained plugin list on Codex.

    I don’t need to spell out how this relates to the long slow death of themes.wordpress.net (where not even the previews work anymore) or the wider strategy of transferring control of community resources from the community to Automattic. Third-party theme repositories are thriving because everyone knows themes are an effective form of linkbuilding: add your link to every theme you redistribute, sell ads, profit! It’s not ideal from a user perspective because you get more links cluttering up your footer, but it’s ever so much better than having to rely on the moribund place your dashboard sends you to, full of broken old themes you have to evaluate on the basis of screenshots. The plugin community doesn’t have any such incentive to build its own resources; so it doesn’t happen; so if Matt happens not to like you, or your plugin, or your plugin’s licence, it’s going to be very hard for potential users to find you.

    Is it just me, or does that not seem very open?

    We seem to be arriving at a point where we rely purely on third-party commercial interests to create and maintain open community resources. It’s become too time and money-consuming for volunteers to do for free. And .org/extend is waaaaay at the bottom of Automattic’s priorities, because serving ads on talkpress is going to make them more money for less effort than selling themes, and plugin distribution is not going to make them anything at all. So I’m wondering whether Matt’s going to have to start rethinking his hostility to those who sell links, charge for themes, and try to profit out of wordpress without contributing a line of core code, because right now they’re keeping the theme community going. And without a theme industry, what would you have? Ye Olde Kubrick and some ancient thing Dave Shea threw together in his spare time. Impressive.

     

    • Jeff Starr 6:27 pm on April 9, 2008 Permalink | Reply

      Couldn’t agree more. In terms of the “hotness” factor, WordPress has been dead for quite some time. Will that stop them from shoveling out upgrade after upgrade ad nauseam until the cows come home? No. I for one am tired of contributing my time and energy to a platform that seems to be selling out at every opportunity, only to watch as the link opportunities dwindle to nothing. For a fresh perspective on content management, check out modx, Habari, Chyrp, Silverstripe, or Symphony just to name a few..

  • codex is dead. here are some suggestions on how to resurrect it. 

    that girl again 3:14 pm on November 10, 2006 Permalink | Reply

    This is one of those posts that started off as a comment and grew out of control, so for context, go here and come back when you’re done.

    I did a bit of codex-related ranting on livejournal, I should probably import those posts :) The fundamental problem is that documentation is far less suited to a collaborative open-source approach than code. To write decent documentation (which is more like a book than a piece of software) you need an editor/manager with a clear roadmap of what you’re trying to do and how it’s going to be accomplished; but as soon as someone steps up to the plate and starts laying down the law everyone else starts grumbling about how authoritarian they’re being, disagreeing with their ideas, and generally focusing more on internal politics than getting the job done. Result? Bruised egos and chaotic docs.

    If Matt genuinely cared about documentation, he’d have appointed a decent technical writer at the outset to oversee the project and get things organised. People are much more willing to accept the authority of official leaders than self-appointed ones. In the early days of the Codex I got tired of my contributions being mangled by fellow contributors who couldn’t even spell right and were obviously just desperate to get their fingerprints on every page they could (you could say that’s the nature of wikis, but that’s why wikis need managing by people who know what they’re doing). Later on, it became pretty clear that newcomers weren’t welcome and the whole thing had degenerated into an egofest. Meanwhile, if I want up-to-date information on a template function my best bet remains to go directly to the code, just as I had to in the days of 0.72. There’s no way codex can keep pace with development when there’s zero communication between developers and documentors and the devs have abandoned it in order to focus on sexier, more lucrative projects.

    Best thing to do? Freeze contributions from the general public. Hire someone to sift through what we have. Keep the useful stuff (by this I mean actual documentation that people can access from their admin pages, not half-baked tutorials which would be better off on a subdomain of wordpress.net). Go through the useful stuff and ensure it’s still useful. Rewrite. Restructure. Tag stuff. (I put that suggestion in there in the hope of getting Matt interested, rather than any great belief in its codex-saving powers. But it may be useful, and should be done). Re-open the wiki with a call for volunteers and a set of rules for them to abide by. Focus on documenting everything in 2.5. Then the wordpresstutorials.com groupies we met in the last post and its surrounding wank will have less compelling arguments for the necessity of their illustrious sponsor, and wordpress will look a fair bit more professional.

    It will not be quick, and it will not be easy, and the temptation must be to junk it like the original wiki and start again on yet another subdomain. If any part of wordpress needed a benevolent dictator, it was the docs. It’s a shame it never had one.

     

    • Andrea_R 4:57 pm on November 10, 2006 Permalink | Reply

      Here, here. Don’t even ge tme started on the documentation (and lack thereof) for MU.

    • that girl again 8:02 pm on November 10, 2006 Permalink | Reply

      I think the general attitude towards MU is ‘if you’re n0ob enough to need docs rather than figuring it all out yourself by looking at the code, you shouldn’t be using it.’ WordPress itself was pretty much the same when it first took over from b2. It drove me nuts, because I knew it was easier to install and use than Movable Type, yet they seemed determined to make it seem as difficult and obscure as possible. I’ve been crusading ever since :)

    • Derek 2:24 am on November 11, 2006 Permalink | Reply

      You absolutely hit it on the head. My POV is one of someone who is not a coder by any stretch, but want to be able to take advantage of the cool things WP has to offer in the way of customizability (if that’s a word…). Let me be clear that I have great respect for the knowledge, time and effort that the WP team puts in to make it what it is, and I have no inclination to switch to another blogging system at this time.

      HOWEVER, both the codex and the forums are damned hard to use. Finding answers in either the forums or the codex is a “needle in a haystack” endeavor, said haystack largely composed of info that is a year or more old. I end up frustrated that the amount of time I’ve spent hunting for an answer is time that I didn’t spend blogging.

    • Mark Jaquith 5:24 am on November 11, 2006 Permalink | Reply

      If any part of wordpress needed a benevolent dictator, it was the docs.

      Agreed. It’d likely be a full time job, too.

      I love helping people and answering questions, but I detest writing documentation and I don’t think I’m very good at it. But if there were an official Codex maintainer, I’d be happy to keep a line of communication open for clarification, assistance, and notification of changes to core WP functionality. Much in the way that Lloyd is helping sort, filter, and manage the bug system, we could use such an intermediary for documentation.

      A good start would be going through and wiping out any old WP 1.5 or 1.2 stuff. That’s only going to confuse people. Also, a lot of the Codex seems to be suffering from “TMI” syndrome. Less is more. Focus on the best way to accomplish something… not every possible way there is to do it. And come to the people who know for clarification. I’ve seen some really awful advice on the Codex… stuff that could be done right if only someone in the know were consulted.

    • markku 4:53 pm on November 11, 2006 Permalink | Reply

      I used to get lots of emails asking for help on WordPress. I usually go to the codex and explain it more simply to my readers to solve their problems. Nowadays though, even I have a hard time finding what I need. Heck, I couldn’t even find the pages I used to read a lot for reference.

      There should be an darth vader of sorts to impose will on the whole codex. ;)

    • Christine 4:46 pm on November 16, 2006 Permalink | Reply

      I remember when I started using WP (back in the pre-1.0 days) and I would ask for help on how to do things. Often, the answer was “Just go to the codex!” Yeah, right. Even then you could not find what you needed.

      Documentation has always been the biggest thing lacking with WP, in my opinion. I remember the early releases of MT, and they always had nice documentation included with the release. WP? Well, hopefully you can just figure it all out. Or find someone to help you. Because the Codex does not cut it.

      It needs an overhaul, and they need to hire someone to do it. You are spot on with that!

  • officially a mug 

    that girl again 6:00 am on March 15, 2005 Permalink | Reply

    The only reason I started posting to the WP forums after a year’s break was that I needed help with theming and the wiki is inadequate. Of course, when you mention that the wiki is inadequate you get the stock response of ‘add to it yourself’. Yes, and if I knew what I was supposed to be adding I would, but if I were in the position of being able to answer my own questions I would not be bothering with your poxy support system in the first place. I would be getting on with coding the bloody theme, would I not?

    Meanwhile they’re bitching on the wp-docs list that they have too many user accounts and any that are inactive after six months should be deleted. Look, you either welcome occasional contributors or you kick them out. Can’t have it both ways.

    (We already had this debate a couple of months back, when lurkers on the list were cordially invited to start contributing to the wiki immediately or piss off. I would have unsubscribed back then, were it not for the fact that this was what they wanted.)

    So, I am having to learn about conditional statements in PHP because the wiki tells lies. No, I’ll rephrase that. I am having to learn about conditional statements in PHP because the wiki predicated the existence of certain templates which the developers, in their infinite wisdom, had decided not to bother with after all. Now, I don’t think it’s that arcane to want your archives for a single day laid out differently from your archives for an entire year, but apparently this is a rare and strange requirement requiring the use of conditional statements, so yeah.

    I still don’t particularly see the need for separate templates at all, but the more you have, the more ‘complete’ your work will be deemed to be, so I’m throwing in everything I can think of. It’s a bit like those essays where you tell the teacher what they want to hear rather than what you actually think. Competitions, I find, are as soul-rotting as customs, but without the rewards. The only decently-sized prize ($150) is getting assigned randomly, which rather depressingly suggests that the lead developer doesn’t believe anyone will come up with a design worthy of winning and has decided to turn the whole thing into a lottery. So somebody who’s done a new stylesheet for an existing theme is just as likely to win $150 as someone who’s gone to the trouble of learning about conditional statements.

    Why have I wasted so much time on this stupid theme? I am officially a mug.

     

  • 'open-source documentation is intrinsically rubbish'. discuss. 

    that girl again 5:41 pm on December 10, 2004 Permalink | Reply

    One of my flist, who has been wrestling with WP of late, found the following sentence on the wiki:

    If you have ssh access, or can change the permissions through a command line interface, use the command “chmod 666 file.php” where file.php is the file that you wish to edit through the Template editing interface. If you can only access your files using FTP, the following resource might be of help: [...]

    Things that are wrong with this:

    1. Is there anyone out there with shell access who doesn't already know how to chmod a file? Really?
    2. It is confusing for people who don't have ssh access, don't know whether they have ssh access, and don't know what ssh access is. There is nothing to tell these people (i.e. the vast majority) that this needn't concern them.
    3. It implies that chmodding through FTP is the weird specialist option for people with limited resources, when it's kind of the other way around. Most users will have uploaded their files through FTP or the control panel, so it's easiest for them to use the same software for chmodding.
    4. It could very well send people running off to their hosts demanding shell access because they think they need it.

    But complaining about the state of WordPress documentation is mostly pointless. I've come to the conclusion that to make a decent stab at documentation you need the following people:

    • A project leader who can define clearly what needs to be done, assign people to do it, welcome new volunteers and keep existing ones motivated
    • A talented technical writer willing to polish other people's efforts as well as writing their own
    • A team of willing minions

    The chances of getting people with these skills to come on board and work without payment are vanishingly small, even if writing open-source documentation didn't happen to be a unusually thankless task (developers are bored by it and end-users take it for granted). People are often reluctant to take on the mantle of team leader if there's no pre-existing hierarchy; but if you rely on people to direct themselves efforts get duplicated, there's no quality control, the minions flounder around not knowing what they should be doing and eventually drift away. There isn't a lot to be done about this — short of hiring people in, which is very unlikely to happen — so if you're going to use open-source software you have to accept that the documentation is going to be rubbish.

    (And yes, I was quite prepared to be a minion, but when the so-called head of the documentation team told me I should switch to Typepad because WordPress isn't aimed at non-tech people, I realised what a stupid idea that was.)

     

c
compose new post
j
next post/next comment
k
previous post/previous comment
r
reply
e
edit
o
show/hide comments
t
go to top
esc
cancel