Archive for wiki woes

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

January 21, 2009 at 9:26 pm · Filed under bubble, Pontification, wank, wiki woes

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…

Comments (14)

business v. business. that is how things work now

April 9, 2008 at 12:15 am · Filed under bubble, design, free beer fundamentalists, megalomania, wank, wiki woes

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.

Comments (2)

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

November 10, 2006 at 3:14 pm · Filed under idiocy, megalomania, pointy-headed fanatics, Pontification, wank, wiki woes

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.

Comments (7)

officially a mug

March 15, 2005 at 6:00 am · Filed under ancient history, design, forums, idiocy, wank, wiki woes

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.

Leave a Comment

‘open-source documentation is intrinsically rubbish’. discuss.

December 10, 2004 at 5:41 pm · Filed under ancient history, bananas, pointy-headed fanatics, Pontification, wank, wiki woes

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

Leave a Comment