Nightly or Stable?

RustIndy — let me answer with a question. did you read the readme file that came with MS-Word?

I’ll take the bet 99% of this thread’s readers answer no. And that 99% of these users also answer no to your readme question.

The point here is related to usability. Users — myself include — do not expect to be reading docs. I did not read the doc of my car. nor that of my fridge. nor that of my VCR. nor that of php, mysql, sql-server or .Net. i just used them. And i — as most users — expect to do the same with my blog.

as for why a few lines should be in bold, consider:

[Current version]
The latest stable release of WordPress is 1.5 and it’s available in two formats from the links below. If you don’t know which to get, download the ZIP.

[Download .zip] [Download .tar.gz]

=> Do you really expect anyone to read what follows the download button? ??

[Suggested version]
The latest stable release of WordPress is 1.5 and it’s available in two formats from the links below. If you don’t know which to get, download the ZIP.

Before you download:

– How to install WordPress 1.5 from scratch
– How to upgrade from WordPress 1.2.x
– To upgrade from WordPress 1.5 beta to 1.5, run /wp-admin/upgrade.php
– More documentation

[Download .zip] [Download .tar.gz]

=> And now your users will have noticed that documentation exists. They’ll remember when they experience a problem.

DenisdeBernardy – feel totally free to create a user page at Codex and produce for us all the documentation you feel we should have and in the format that you think we should have.

frankly podz, i would love to if i had more time. in the meanwhile, the best i can do is to contribute here and there by giving some critics — which i sincerily hope are constructive — and do my best to report and diagnose bugs i find.

speaking of bugs, https://www.ads-software.com/docs/ has a ‘get involved’ topic that points to:

https://www.ads-software.com/mailman/listinfo/docs

it is a genuine 404.

— Denis

btw — who is maintaining the wp web site?

With respect, we have had people – a lot of good people – working on docs for months. Those people too don’t have the time that docs warrant spending on them but write them they do.

As callous as this sounds, if you want to help, please do, but criticising from the sidelines does nothing except exasperate those who at times feel they cannot please anyone.
Satisfied users just get on and blog – disatisfied ones make noise and believe me, it can get very very demoralising when that is all that is heard.

This site is maintained by Allusion (Matt).

“i’m just a little irritated by how complex the switch from 1.5 beta to 1.5 turned out to be.”

What on Earth are you talking about? Did you read the upgrade instructions? Delete files, upload files, run upgrade.php. Why is that so difficult? Let me call your attention to Step 4: “Upgrade” https://codex.www.ads-software.com/Upgrading_WordPress#Upgrade

“In your browser, navigate to your wp-admin folder so that you can run the upgrade.php script. It may be somewhere like this: https://www.example.com/wordpress/wp-admin/upgrade.php. NOTE: Your path to the wp-admin folder will depend on your installation.”

Are you saying that it’s too complex to read, comprehend, and follow all upgrade instructions, which you were linked to directly from the new version announcement and the download page?

Also, the readme file states:
“Upgrading from any previous WordPress to 1.5:
1. Delete your old WP files, saving ones you’ve modified
2. Upload the new files
3. Point your browser to /wp-admin/upgrade.php
4. You wanted more, perhaps? That’s it!”

So, from what I understand, the only complexity issue here is your ability to follow directions.

He already said he didn’t read the directions ??

So, the complexity is the result of not even reading the upgrade instructions which are linked to directly from the new version announcement and the download page, and presented in the readme. Then, under what grounds can he call the upgrade procedure “complex”? He doesn’t even know the upgrade procedure.

podz: yeah, i know. i’m in the software business, i perfectly understand your point, and i sincerily don’t want you — or moose, ryan, matt, or any other developper — to take anything personally.

regarding your remark, documenting software is not so much about producing pounds worth of paper than about producing a tool that requires little or no documentation in the first place. as an aside, and quite frankly, i think wordpress itself is not very far from being idiot-proof.

now, user-oriented workflow and general estaethics put aside, the main focus to make the software more usable is to provide contextual help. simply put, no amount of codex pages — which works very much like an html encyclopedia — will replace the right line at the right place (with a link to said encyclopedia).

hence, i can only i disagree with you: criticising from the sidelines is one of the best ways to contribute when it comes to contextual help. more so when it tries to be constructive. irritated “i was trying to do this from there… it did not work as expected!” type reports, no matter how unconstructive, should prompt an immediate “why was the guy trying to do it from there in the first place?” followed by a “how do i make this more obvious?” when relevant. and the only way to usability test thereafter is through trial and error until said irritated reports disappear.

example (and reply to macmanx):

“how come we got so many users who did not run wp-admin/upgrade.php when upgrading from 1.5 beta to 1.5”

[thinks hard]

1. because as a rule said users never read the readme file

2. because said users stopped reading the installation instructions when they found the download button

3. because said users expected no major difference between 02/11/05 code base and 02/17/05 code base, only bug corrections

4. because said user assumed upgrade.php would automatically run itself

[thinks hard for steps to increase usability]

1. as a rule, users only read docs that are short and simple, i.e. to do blah blah go there, do this then that and click apply. 1 line for title, 4 bullet points of instructions at most (*). write more and only the bravest will read.

2. strategically put installation instructions before download link, and put link to faq and codex — nevermind: to “Frequently Asked Questions” and “Documentation” — towards the top of every page in the support forum.

3. put warning in bold on download page because it is really not obvious. see 4, however.

4. change upgrade procedure

a. store current version and last backup date in options table
b. auto-run upgrade.php and auto-backup user data without even asking the user whenever necessary

(*) there is a reason for 4 at most.

as you probably know already, users can manipulate 7, +/- 2 pieces of information — or groups thereof — at once without any problems. it is the reason you’ll more easily memorize the second of the following:

3 – 6 – 2 – 7 – 9 – 4 – 6 – 9 – 4 – 8

36 — 27 — 94 — 69 — 48

7 – 2 = 5, so you’re safe with close to all individuals by choosing 5.

however, there’s an equally important yet much less known experiment which shows 4 is the maximum number of items you can apprehend without counting. this holds for animals as well (e.g. a bird can count to 4). consider how many there are:

III

IIIIIII

IIII

IIIII

like a bird, you count 1, 2, 3, 4, lots! except when you concentrate. and users are no different. hence, 5 bullet points need a lot more extra effort than 4. so we choose to stick to 4.

From then, you can group and most users will not even notice the complexity. they’ll notice even less if the details are accessed using html anchors. consider:

1.

– a.
– b.
– c.
– d.

2.

– a.
– b.

3.

– a.
– b.
– c.

4.

– a.
– b.

I still have trouble grasping how this could possibly be “complex”:
“Upgrading from any previous WordPress to 1.5:
1. Delete your old WP files, saving ones you’ve modified
2. Upload the new files
3. Point your browser to /wp-admin/upgrade.php
4. You wanted more, perhaps? That’s it!”

As for the users who don’t acknowledge the upgrade and installation links before clicking the download button, there’s little more we can do other than encode a javascript popup message into the download link.

someone has way too much time on their hands!

sure, it is very simple indeed… if you’re aware you must do it. and as i just pointed out:

– there might be a few ways to organize the information that will make more users aware of the solution.

– there’s even a way to bypass the difficulty entirely

1. because as a rule said users never read the readme file

2. because said users stopped reading the installation instructions when they found the download button

3. because said users expected no major difference between 02/11/05 code base and 02/17/05 code base, only bug corrections

4. because said user assumed upgrade.php would automatically run itself

Said user needs to learn how to read instructions, or said user will learn a hard lesson some day.

1. as a rule, users only read docs that are short and simple, i.e. to do blah blah go there, do this then that and click apply. 1 line for title, 4 bullet points of instructions at most (*). write more and only the bravest will read.

That’s what this is:
“Upgrading from any previous WordPress to 1.5:
1. Delete your old WP files, saving ones you’ve modified
2. Upload the new files
3. Point your browser to /wp-admin/upgrade.php
4. You wanted more, perhaps? That’s it!”

strategically put installation instructions before download link, and put link to faq and codex — nevermind: to “Frequently Asked Questions” and “Documentation” — towards the top of every page in the support forum.

That’s a nice suggestion.

3. put warning in bold on download page because it is really not obvious. see 4, however.

The difference between hyper-linked text and regular text should be enough for the average human.

4. change upgrade procedure
a. store current version and last backup date in options table
b. auto-run upgrade.php and auto-backup user data without even asking the user whenever necessary

There are plugins to do automatic backups, and procedures to do manual backups. The decision to backup has been and will always be up to the user. Also, auto-run installation and upgrade scripts pose as a security risk to any and all web-based software. This is why most web-based applications (specifically open-source apps) require manual activation of the installation and upgrade scripts.

DenisdeBernardy – I take your point.
However (there had to be a ‘however’ ?? ) I would argue / discuss that the target audience needs to be considered.
If we use your example of MS-Word …. I would like to shoot the guy who invented that bloody paperclip piece of junk ?? No doubt some people like it and find it useful, me ? No no no no no – hence my use of Open Office. I’m sure that research for MS says that the paperclip is useful – but you can guess the demographic of those that nod and smile when it is mentioned.

WP is used by a very diverse bunch of people and they go from the coders who download and dismember without a problem, through to the person who posts here asking for different smilies on different pages but without having to alter code (and can it run in an iframe and look all cool just like so-and-so’s page who you then discover isn’t using wp at all anyway but who does have a page 500 validation errors…. etc). That’s quite a range, and arguably, before you can start sticking quick links or popups in, you need to be aware of what can be done – and thats the point of Codex in that it is open to the community to write in.

I’ve always found WP to be intuitive in the 13 months I’ve been using it, but there are two things that must be borne in mind:
1 – Some people will never RTFM. (I don’t)
2 – Some people will never “click and see” even though it’s safe to do so. (I click everything until it breaks)

I can see where you are coming from, and if there was a month’s paid work on offer to document WP then you and everyone else would have some quality work to read, but this is open source and while coding a plugin is sexy, writing a doc on how to use a template tag just isn’t seen the same way.
It’s also the case that WP is free, and even though Matt says on a page around here somewhere that a contribution in the forums or to the docs is welcome, more people doing so would be welcome.

I would suggest that you sub to the (just working again) Docs list and maybe you could contribute that way (bearing in mind that as I said before we do have a lot of work done and some agreed guidelines) ?