Working on it.

On Codex

Codex…So given that I did write a lot on Codex, why don’t I now ? The reasons are not as simple you probably think. Not that they are complex either.
At one time I did write a lot of basic stuff to do with WP. Those guides are no less valid today than when they were written – let’s not forget that people very new to blogging and web-code download WP daily – and Codex features my work in some state or another (more on that later). Anyway, I had written quite a few bits and pieces and I had transferred my work to Codex. I did this at a time when there were only a few of us doing this (Craig / Carthik ?) and we wrote up what worked on the forums – quite simply if it was passing the “Forum Test” then that was good enough for us. So we chugged away …. I proposed a “Wiki Day” where people would chip in to the development of Codex and I have to say that thanks to the huge contributions made by many others, it proved to be a great success and it’s momentum probably continues to this day thanks to the tireless contributions made by Lorelle, MDAWaffe, Kaf and others. Unfortunately for me, just prior to Wiki Day, I got ill and it took a long time for me to come out the other side of that period. As I did, two things happened;
– the first event (as some of you will have guessed) was the words and proposed actions of another person followed by what I saw as hurtful words in the forums. Even today this event is alluded to by others yet the harm that those same people (not the person who started it) did has not been addressed by them. Meh – it’ll never happen. Either way that event severely knocked my desire to help. Ever get thrown out of a loop that you were once really into ? It’s hard to get back.
– the second event was that all of a sudden the “Forum Test” just was not good enough for Codex help. There were discussions about the order of words in headings, how to write things that were ‘usable’ and coming from a background where I spoke in a language that people understood I found this prevarication a waste of time. Maybe there are books about usability and how people read and comprehend, but given that this research is – in the context of education – very young, and that the people who wrote it got to where they did by using ‘old fashioned’ methods then why all the fuss ? (I am very anti-guru / anti-new in many ways such as this. I see much of it as building castles in the sky and convincing people to not only see them but rent them out too). This sounds like I am knocking those people that feel such topics are important to codex and WP – I am not. I am knocking the principle of the thing. I’m not a writer of docs. I’m a trained nurse, I taught by doing not telling, I talked in a way that was understood and not politically correct or otherwise altered and if anyone fell into writing docs it was me. Bear in mind that at that time, users were not complaining about the wiki and that like with any project you give a lot to, when others start criticising it the ability to stand back and see things objectively can be lost. That’s probably explained badly but I hope the gist of it all comes across. It was fun for the novice that I am, but given the markets that WP now faces – and wants to yet face ? – better people are now around.

So, I came back to the world of WP where at that time I did not feel like I wanted to contribute and knowing that even if I did my work would be changed – as it had already been. Hmm… hardly great eh ? So I stopped. Pretty simple really.

I DO understand the principles of a wiki and in so many ways I applaud them, but seeing that someone has logged into a page you created and then punctuated it in a way that actually alters the emphasis – because I wrote it in English and they have decided to punctuate in American – can get pretty annoying when you see it happening repeatedly. Maybe I’m sensitive .. but then I recently posted here about the future of WP only for Matt to point out that the item I had highlighted was not added by a Developer. Such is the way of the wiki… bah.

Codex itself: the documentation would not be in the excellent state it is unless Matt had made the decision to use mediawiki – it’s a powerful beast – and with the way WP expanded only a wiki would have done (and will do). It’s something I feel comfortable using (though I now use dokuwiki on my machine) both as a contributor and a reader. I do not think the same holds true though for new users. This is NOT a docs issue – it’s about everything around them. Codex can be quite cluttered in it’s display which can make reading information distracting. Additionally the structure is totally unlike the websites users may be used to, and I also think that colour is something that is missing. I really do think that we would be doing new users a huge favour by replicating more of the basic information and making some static pages (I’ve heard WordPress can do this ;) ) for those errors that repeatedly crop up – after all, will the cause for “Headers already sent” ever change ? Not my decision but I don’t think the effort would be wasted – the confused and puzzled need clear pointers and familiarity. When they are ready to jump in more fully, Codex can have them.

In the end though, I don’t want to get pissed off because someone is hacking my work to bits to make it more ‘usable’. I would rather hang around the forums and talk in whatever language works there – no, that’s not a dig, it’s just the way it is. You can tell a lot from a URL and a choice of username….. and if I ever do distill a flawless guide to databases, I’ll write it. And now you know why Codex isn’t where I am, but I really do admire the tremendous work that others have put into it. I was in the right place at the right time to create the docs that were needed just then. Time moved and I can now point to the foundations of Codex and say “I did some of that” – and that’s no bad thing is it ?

[Apologies if I did not mention your name – no malice intended and if I did mention your name I hope you don’t mind !]

Post navigation

14 thoughts on “On Codex”

Thank you for this Mark. It is only recently that I have thought about contributing to Codex – I had in mind some CSS positioning stuff, floats made simple, 3 cols for idiots and 3 to 2 col switching templates. Nothing fancy. Now I have a certain writing style. And I do not know how I am going to manage my work being edited by other folk. Do we need to adopt US spelling for example? Obviously we do. There are also in the codex orbit one or two people who are IMHO excessively proactive. It is not always a good thing. Successful coordination of a lot of muleheaded volunteers requires tremendous delicacy. Finally the interface is not immediately accessible. I do not say for one moment I cant manage it. But like anything it takes a bit of time. Longer than I expected I guess.

I thought this kind of thing had only happened to me. I decided a little while back to add my little bits of limited WP wisdom to the Codex, mainly in the form of theme lists, but when I returned to the Codex some days later, my own wording and links had been changed.

I felt a bit annoyed and consequently deleted my references. In my opinion, the Codex is too controlled by others who think they know what is best for everyone.

Ditto. Every time I added something to the old wiki it would be mutilated so that it no longer made grammatical sense. (I have a masters degree in English literature so you can imagine how much this ticked me off). Besides which, my understanding is that Codex is GPL, so if people want to lift your tutorials and republish them without credit they can. I’m afraid I’m just not altruistic enough to contribute under those terms.

“Besides which, my understanding is that Codex is GPL, so if people want to lift your tutorials and republish them without credit they can.”

The same license under which WP developers and plugin authors do countless hours of work.

Thanks for sharing your thoughts Mark, it’s interesting but in a frustrating way that I wouldn’t know what to do to make it better. Some things about wikis do frustrate me, notably that they can be hard to get around, but the tipping point for me was just getting over my ego and knowing that ultimately what I contributed was bigger than myself even though it might not have my mark in the way I would like it to. The loss of control is disconcerting, but necessary if you want to create something with a legacy.

Matt – I do not think you can do it any other way. If I did, I would have said so.

I tiptoed around what you call – quite rightly – the “loss of control” because it is an area that had I waded into would have taken the focus more away from the points I deliberately set out to make.
I will say this though: WP code is governed ultimately by two people (yourself and ryan I assume) while WP documentation appears to be governed by the person(s) with the most ‘right-on PC’ views who bang them out to only the right people until they are heard and acted upon. I have used the term “Seagull Management” before in this respect. Codex needed – and still needs – an overall arbiter. This arbiter should take advice and in the end make a decision and people must know who that is – right now there is no one person in control of codex on a day-to-day contribution level. I really do think there should be.

When a wiki is being used to create a final document with a team input that is one thing. But in a company presumably there would be an editor and some demarcation. Here there is no *final* version. It is in a permanent state of flux. Inevitable perhaps but it is a completely different set of circumstances. I can think of at least one person whose technical ability; at least in the area I am interested in; is fundamentally unsound. But the same person is very proactive in editing other peoples work. Go figure.

Note that on the page I did, there is a direct clickable link to The Really Important Bit. Why ? That has and still does catch people out. I CAN understand that the installation information needed collating, but I CANNOT understand the non-linkage, except that the person who did it very probably did not use the forums much.

I will give my time to docs IF:
– the status of the docs is more clearly indicated to all users
– if there is an arbiter who will explain actions.

The example I give above is only one .. and I’m sure it is not just limited to me.
And the people that will disagree with me ? They are the ones who do not contribute as much as correct. One takes effort, the other takes pedantry.

I don’t think it’s possible to have a single person “in charge” of Codex. There are just too many who will wave the “freedom of speech” flag and spend all of their energy pissing and moaning about why Thing One was done and not Thing Two and so on.

Not only that, even making a suggestion can set you up as a target. Recall when I suggested that any account that hadn’t been used in a certain amount of time be deleted. Setting up an account takes less than a minute, and a whole pile of accounts were set up and never used for whatever reason. I figured it would be nice to dump the inactive ones, and reduce some clutter. Remember how I got dumped on over that? People who never actually contributed come out of the woodwork to shit all over me and my suggestion. IT WAS A SUGGESTION. I posted it for discussion. Instead, I was raked over the coals for even thinking such a thing. That was it for me. I have not contributed to Codex since that time, and it’s unlikely that I will ever again.

It’s no different that the crap I took as a result of my efforts to keep the WordPress forums on track when so many people were shitting their pants over the ads on WordPress.org that resulted in WordPress being removed from the Google index.

I have lost most of my interest in doing anything with WordPress or for WordPress. Something that used to give me some pride and a sense of accomplishment has turned into something that leaves a bitter taste in my mouth. It’s hard to even add content to my own site, never mind work on making the design and function one that is distinctly NuclearMoosian.

When four times as many people call you a Nazi as thank you for your help, you know that your contributions are no longer of much value.

As a former member of the docs ‘team’, I can relate to a lot of frustration here, even though I ceased to be an active member a year ago (wow, has it been that long?)

I’ve remained in touch with what’s going on…the mailing list, the forums, the Codex. Here’s my perspective: the Codex is the only thing that’s really changed in the (almost) 2 years I’ve been hanging around WP. Even that, for all the great work that’s gone into it, is basically a shined-up version of the original WPwiki.

During my time (I say from my rocking chair, holding my cane ;)), I’ve seen the WP code go from .70 to 1.5.1 and undergo considerable change..not only in the codebase itself, but in the means of distribution and reportage (use of Subversion and Trac, for example); I’ve seen the docs become more plentiful and useful, but in 2 years, all the same old complaints and frustrations are still there: nobody reads them before asking questions, nobody appreciates the work that goes into them, everybody’s all too willing to bitch and nobody’s willing to help. The medium of exchange or distribution hasn’t changed; in some cases, fundamental docs like the ‘5-minute Install’ haven’t evolved much since Craig and I spend a couple of feverish days kicking its tires to have it out in time for 1.0. The FAQ linked on wp.org has been in place since late 2003/04, and has not been updated since then. That seems incredible to me.

What’s the solution? I think (and have always thought), that in order to have a ‘team’, you have to have a ‘leader’. The difference between Craig and I, when we were co-leaders of the docs team, is that I’m willing to be a bitch and he’s not. :) The docs team is not, should not be, a democracy. It’s a meritocracy based on quality output. Part of the inferred definition of ‘quality’ is that it adheres to some sort of standard. Piteous cries about ‘freedom of speech’ have nothing do with anything (when it comes to writing docs..the forums are a different situation.) However, it doesn’t do any good to have a ‘leader’ when Matt can so easily (and has) override his/her decisions. This effectively undermines anyone else’s ‘authority’ to make decisions or arbitrate disputes. Until a time comes when Matt is willing to back off and trust someone to do the job well, there will never be a docs team ‘leader’ in the true sense of the word.

I think you have the right idea about your guides, Mark. You have control over what they say, how they’re presented, and some control over how they’re disseminated. Although the docs team certainly has the resources (via the Codex) to *write*, they have very little control over how the docs they write are presented, distributed, or administered.

By virtue of being a wiki, the codex allows itself to be flexible and open to change. Anyone can come in and come out; there are no barriers. Contrary to many, I think that, on the whole, this is a strength rather than a weakness. It is because of this virtue that we have seen some of the marvellous contributions to the codex that exist.

The open wiki format was necessary for the codex to grow to a “critical mass” of information. I think people would have been a lot less willing had they had to step through approval loops before their contribution be made valid.

Cena wrote that the codex has been the only doc entity to have gone through major change. This is a testement to the success of the wiki system underpinning it. How much harder would have it been for a predetermined documentation team to have generated the same amount of info? How much harder would it have been for the growth to have continued?

That is not to say it’s perfect. Once you put something up on a wiki , it is no longer yours. What you’ve done is given it up to the community and to a certain degree it’s now out of your hands, and out of your total control. It’s not always easy to see something that you started change (for better or worse) but you trust that what you set free to be an overall positive and you trust the community to be a positive force.

You can, of course, trade some of that open freedom by appointing “gatekeepers” who act as arbiters of the info. However, by doing so, you have to realise that you’re now putting constraints and that comes with it’s own set of costs.

If Else – yes, but Codex already has it’s own set of self-appointed gatekeepers.
Craig’s post from 14/3/05:

“Anybody know if it is possible to blow away accounts that haven’t been used after x number of days/weeks/months?

Looking at the user list page, I’m shocked to find out we have 841 registered accounts. Given that some of them have never done anything, and others are spammers/vandals, shouldn’t we clean this up once in a while?

I guess by “we” I mean Matt, since he is the only one holding the keys to the executive washroom! :P “

From that point, Craig had a ton of shit thrown at him for NO good reason. None. And the people screaming the loudest ? The ones who had no right to do so if this is in fact to be a meritocracy.
I totally support Craig in his post.
I even asked if we could have a polite debate and was blown out.

Let’s take a look at Codex….. today, someone called “Mabel” defaced Codex. It was repaired. Now Mabel can deface the Codex every 30 minutes if she wants – but you cannot delete her. Instead, she will be blocked by IP – something we are constantly told by “those that think they know better” is a BAD THING. So instead of making life harder for that one user, or by using other tools that are at coders disposal, we are blocking – for however long – any and every legitimate user of Codex who just happens to have that same IP. Why is that acceptable when in the forums we tell people that IP blocking should not be used ?

Fact is that I believe that just as in real life, you have to earn the right to have your opinion listened to. In real life you would not put so much weight with the newest member of staff as you would with a time-served person – why should online be any different given that some of us (Craig / Cena) have been around WP for longest and have a better overall picture.

It’s very simple – some people are more equal than others, and the details I posted above illustrate that. Want to check ? Go look for positive and consistent contributions for most of the people pissing on Craig that happened before and after that incident. What surprise – there aren’t any.

Now I’m going to pick on a word – “legacy”. Is there anything you can think of that could be called a “legacy” that did not have a leader ?

Okay, so let’s say the account was deleted, the person would just register a new account. Or use a proxy and register an account. Or use a botnet and register a thousand accounts and ruin the Codex beyond repair. We’re not treading new ground here, the Codex works the way it does for a reason: it’s worked for creating the world’s biggest encyclopedia, the Wikipedia.

I’m perfectly willing to block IPs at a firewall level or delete accounts of abusive people, but Craig suggested that all lurkers be deleted. It’s not surprising the lurkers jumped out and said “Hey!”