WordPress MU

Documentation, its a concept most developers supply with software solutions in order to provide common instructions and configuration information for users of products.

Apparently the MUWordPress people felt such a concept is so ridiculous that why bother. After all most novices certainly understand things like HTACCESS and Server Settings at birth.

Well I spent an hour on the phone with a client who told me he could find no documentation when I knew damn well there had to be since wordpress was in the name. Dude was I wrong and an hour on the highway on my cell phone really angers me when I get back to my office, configure the MU install for my client only to discover that there is NO DOCUMENTATION of ANY KIND. LOL I thought I'd seen everything in this business but apparently I never could get past the MUWORDPRESS crew not providing a /documentation or how-to-install.txt file with the distro.

I'm not upset anymore. I'm making it my business to write quality step by step documentation on my own blog so when people do a google search on the subject they will find me and then I can say what I want.

You guys are straight out of a comic book.

Um, maybe the README.txt file?

http://trac.mu.wordpress.org/browser/trunk/README.txt

Only file named in capital letters in the install. Kind of hard to miss.

And WordPress Multiuser isn't for novices. Even says that in the README.txt file. You did point that out to your client, right?

I guess your writing skills have developed so much that you may need to work on your reading skills as missing a file labeled README doesn't say much for you. Maybe looking at all those spandex covered tits in those comic books isn't such a good idea. :)

edit: Oh wait, I just found a post on your blog where you got banned from a forum because you didn't read the rules. Guess that just proves my point.

Ummm I was actually being serious drmike. The readme.txt file isn't documentation of any kind and you know that.

And about being banned. Dr.Mike maybe you should re read the post yourself as the reason behind my ban wasn't my failure to read it was my signature link going to my blog where I discuss alternative solutions NOT MENTIONED IN THE FORUM RULES AT THE TIME. But I've removed the post because its clear others will not fully understand either.

So to clarify before you get upset I'll just say that documentation is sparse at best. WordPress documentation is EXCEPTIONALLY EASY TO FIND but I notice here that the same questions get asked over and over and over again. Hmmm, I'm at least partly curious as to why. I mean in WordPress docs or should I say documentation are easy to find and I was amazed to discover that this guy had such a problem with this build. Sad but true, when I verified it, he was in fact correct. He really could not find organized documentation.

I'll write some documentation when I have the time and publish it which you are free to distribute. Not everyone drmike has the same knowledge about wordpress as you and I do and even fewer use this product so I find it unusual for a moderator to take such offense. Whats wrong with just saying it could be better? And why as a moderator in a position of responsibility did you think my post on my blog had anything at all to do with documentation? LOL, okay whatever.

I was being serious as well.

It's nice how you've changed your "complaint" from no documentation to not the correct documentation.

As to the offense, maybe you should reread your post as it was rather insulting.

And no, I'm not laughing. For someone who is a web based business, it worries me as to what level of service you're providing when you can't even find a readme file, especially the part about not being for novices. Wordpress multiuser requires experience with wordpress. If a person does not have experience with wordpress, then WPMu really isn't for them. As to you not understand that, it troubles me even more.

Have you even read the readme file yet? Changes in DNS and Apache are not for new users.

The readme.txt is perfectly adequate for installation. If you don't understand a concept that is in there then that is not a shortcoming of the documentation, it's a shortcoming in your own personal knowledgebase. Or your client's. Whatever.

Rather than complaining about the lack of documentation (that is clearly labeled in the root folder), why not just let everyone know what you think is missing or could be expanded upon in an effort to improve it for the next guy?

Or at least ask if you're stuck on something? I don't mind stupid questions as long as you've at least tried and show that you have. All those threads you see asking the same questions over and over again are liking from folks who 1) just want everything handed to them and/or 2) didn't search.

I was short and out of line in a hurry and annoyed fully my error in my tone. I do apologize for not being clear and I should have been less annoyed since I myself have never needed such documentation so it never crossed my mind that there was little available for some guy new to this.

For someone who is a web based business, it worries me as to what level of service you're providing when you can't even find a readme file, especially the part about not being for novices. Wordpress multiuser requires experience with wordpress. If a person does not have experience with wordpress, then WPMu really isn't for them. As to you not understand that, it troubles me even more.

drmike, I'm not arguing with you about this, okay, I'm not the student I'm the professor and I didn't come here to find things for ME myself and I know you didn't missed that. I came here to verify if this new guy was bulling me or not that he couldn't find documentation on the things he was after. I verified that yep, he's right, there isn't any. OOPS did I open a can.

So, why is that so difficult to understand that the readme.txt file is for basic installation (of sorts)? Do you really consider a readme.txt file as documentation for some new dude who can't understand the concept?

But honestly, rather than continue with this and get your Irish temper in a flare to where you gravitate to unethical behavior I'm revising my position to simply this and washing my hands of this thread; In FACT! Delete it if you desire.

I'll take the personal time to write a clear outline for guys that are new to server admin, mod rewrite and the like. I had just assumed there were such clear written pages on such things here. I was wrong and I can admit that.

I had a "great" reply, but I think I'll stick to not wasting my time with such ignorance and a lack of manners/etiquette.

LOL

Now that the apologies have been said, and everyone is talking nicely what can we do about getting a wiki or something setup so that drmike and lunabyte and so many others don't have to repeatedly tell people to search. Some people will continue to use wpmu who maybe shouldn't; we can't stop them. I myself am fairly new at this, but I have been playing with wpmu for a couple of years, and I spent a lot of time in google and in the forums looking for answers. The documentation doesn't have to be for beginners, but over and above the basic install problems, which are very adequately discussed in the README, there are so many issues which are spread out over 3, 4 or more forum threads. And, as has been said more than a few times, it isn't always easy to find what you want in the forums. I would, and php4ever has also -after admitting the tone of his first entry was wrong- graciously offered, to help write documentation (I realize I may not have the expertise for some pieces, but I could do some of the bulk writing and then leave it to others to tweek and edit). This is a great piece of software. We aren't all using it to make quick cash. I use it for a group of about 100 students, and believe me the difference in time of trying to administer 1 wpmu versus 100 blogs is a life saver. This is great software and a great community, why not work on this together?

FWIW, It seems to me that there is a lot of pretty good documentation out there on WordpressMU, certainly if I compare it to the typical open source project.

The WordpressMU team has setup a pretty good forum (this one) that is very well covered by volunteers like Dr. Mike and Lunabyte and many many others... and since WPMU is based on WordPress, all of the documentation for WordPress applies to WordPressMU except in cases where the team (and the community) has taken the time to document the differences. (Mostly in this forum.)

If indeed php4ever is a "professor" then I would hope that he is teaching his students how to "learn", and since a big part of learning is "finding the answer" then I am surprised at his initial post on the subject. Seriously, I'm not trying to pile on here, I'm just saying, it's a little surprising.

Now, would a wiki help? Maybe... Jalien, would you like to start one?

Certainly one downside to forums is that they can get out dated... wikis are better in that regard.

But then again, magazines and books can get out dated... maybe we should stop visiting libraries in our quest to learn... god knows they don't have "documentation" there.

Here's the important thing about open source projects like this one... if the existing product or documentation doesn't meet your needs, then FIX IT and give back... "Pay it forward" as they say.

I try to do my part, by jumping in here to the forums every once in a while to help people with questions that I know the answer too. I've tried to post some helpful code now and again. But others (Dr. Mike, for example, who is a VOLUNTEER!!!) have done so much more.

So please php4ever, don't run away, don't wash your hands of the thread.... take it as a learning experience, that the community could use your help. Suggest that this "student" take the time to write some documentation. He or she is a student of yours, right? So they should be ready to learn? Right?

Pay it forward man.

Thanks... in advance... for the great work that you and your student will contribute to WordpressMU.

If you need some help on writing a chapter on mu-plugins vs. plugins, I'd gladly add a hand...

I think a wiki was already started, I would add my limited knowledge from the little experience I have had and hope that it was added to and edited by those more in the know.

A wiki would have to be labeled beta and new users would probably find it frustrating with lots of holes for a few months, but Iwould rather the wordpress gurus spend time working with security issues and adding the features and tweeks that we all want. I had a terrible time with my first intstallation, but it has gotten me to learn and share some of the learning with others, some through this forum.

someone had set up a wiki once (http://www.wpmuwiki.org)but it's down, perhaps one will emerge one day that becomes a good documentaion and reference manual. It would be cool in my mind if we added one at http://wpmudevorg.wordpress.com

I actually agree with the sentiment that there is 'sparse' documentation. For what it's worth, i spent the last two weeks trying to get a basic installation of WPMU up and running, and ran into issue after issue which just made the whole thing more trouble than it was worth.

Yes - I'm not a server or WP expert lilke some of you, and yes I'm also not a php genius either... but I was able to get WP working with the same basic skills and have been using it for over 2 years now solidly as a result. The support base, documentation, community and general interest in WP is massive imho compared to WPMU, which is a shame since I see a lot of potential in wPMU if I could only get the damn thing working.

This is not a gripe or a sideswipe at the folks who are involved, no doubt doing their best. This is an observation from someone who came to WPMU as a solid fan of WP, with a desire to get a specific site/concept up and running using WPMU who has had to abandon the idea and look elsewhere because WPMU is just not user friendly enough yet. Maybe some future release will be - but getting information on that seems to be tough too.

So - admin types - don't take this as criticism or bitching please, because it's not intended to be. Just take it as honest feedback from someone who has spent many weeks now looking at WPMU, Joomla, OSCommerce, Mambo etc. and all variations of same - trying to find an opensource solution which would meet my needs.

The hunt still goes on, unfortunately.

The wiki at (http://www.wpmuwiki.org) was started by the same guy who so nicely provides http://wpmudevorg.wordpress.com.

I'm pretty sure it's down because of lack of posting to it. people bitched abut it till someone did it, then nobody contributed (okay, a handfull of people).

Documentation here is the same as for regular WP: most of it is done by the users. THe devs have made no bones at all about that in the past. It's not user-friendly because it's not install-and-click software.

you wanna write docs? FEEL FREE. It'll cross a bunch of my volunteer list. And drmike may be a mod, but he's not on the payroll either.

I really am kinda tired how people point fingers and blame at drmike and us regular forum volunteers, but the reality is - we who help you the most have no say. Or very little. And the things we can document get lost in the forum, the codex is a mess, and any privately-run sites get no official mention (which is kind of expected, but still. Unhelpful.) In reality, we could all write the best docs ever, but if they aren't tied right in to this site, we get stuck in this endless loop.

The devs have released the code and the code only. They've long said documentation is up to users. You can bitch at the devs all you like, but keep us volunteers out of it please.

Agreed wholeheartedly Andrea.

While there isn't much difference between WP and MU, the differences that do exist are big ones. Which is what also brings in the need for the end user to have more experience with certain things overall.

andrea_r sorry if the tone comes across as whining, but really I and I think others would like to help so that the volunteers like you and drmike can spend your time helping with real problems.

Could we try again at the wiki? Do you think andrew billits (wpmudev) would put it up again, or since he has the wpmuwiki.org name let it be used again? I would be willing to try and contact him, but if someone in the forum already has contact that might be a better route to go.

I think it sounds like the time is right to try setting up the wiki again. There are a lot more people who have gone through the basic learning stages of setting up and running MU, and in this forum and the sticky As lunabyte said, the differences between WP and MU are big.

I'd like to ask everyone, what practical steps should be taken.

As you said Andrea, "privately-run sites get no official mention". Could a sticky be put up with links to the documentation, and some other sites like wpmudev.org, or the links could be combined with the "search" sticky. If hosting is needed, I don't have hosting myself to offer, but I'm willing to add a little if that would help. What kind of requirements would we need for this do you think? What other issues need to be considered and planned for? How can we make this self sustaining without relying on any one person to try and carry the load? There is a lot of experience out there, let's put our heads together and come up with a solution.

drmike, andrea, lunabyte you all have put a lot into these forums, how can we help you? What do you think would work best?

Aw, now you're making me all mushy. Well, since I can't figure out how to make a 36 hour day, here's what I can think of off the top of my head:

If you see a question you can answer, do. Even if it's a "works for me". Especially if it's a really simple one that could be answered by a simple search.

Point people in the right direction. Loads of good plugins are off-site. newbies need to know where to find them.

Help prioritize. Sometimes there's so much stuff flung around, it's hard to know where to start. :-/ Many days, there's too much time spent in putting out small fires so there's no time left for ongoing long term things.

Whip up a plugin if you can.

Make lists.

Test things and report back.

Contribute to the codex, even if it's just a couple of lines.

Realize we all have lives ;) and despite the fact that most of the top half a dozen posters appear to be here pretty much constantly, sometimes things beyond the screen affects things. A spoonful of patience goes a long way. (yes, both ways)

I'm here for the love of the code, honestly. (even when I complain) I devote my time because it's interesting, fun, and pretty darn good. I * believe* in its potential for a good Internet experience for possibly millions of people who sign up for blogs on all our sites. And *that's* why I'm here. :)

Again - it's not whining, it's an observation from someone who actually likes WP and wanted to get into WPMU - so enough already.

I don't have the skills to write up a doc from scratch on this product because I'm still a newbie at it, but if someone wants to send me the source material (links to the most important questions and associated answers) I'll gladly pull a FAQ together and even host the damn thing if it helps.

I'd love to see WPMU developed into a more user-friendly product, or at least some user friendly documentation for those of us who are not as skilled as you guys though.

c0y0te

At the risk of having this thread go on past it's useful life, let me add the following observation.

There is a common complaint about complex systems that "the documentation is insufficient". The main reason for this complaint is that there is a wide range of styles and skills of classic research skills amongst the "seekers" of information. I'm not suggesting that WPMU is "well documented" but my point is that even for systems that are "well documented" it is common for this complaint to exist, and this complaint is much more likely the more complex the system being documented is.

For example, consider: the Windows or MacOS programming APIs, Java, PHP, or SQL. There are countless volumes of documentation on these systems, yet many many many people struggle to find "good documentation" to meet their needs.

WordpressMU, like most open source software package is much more akin to a programming toolkit than it is a "shrink wrap" software package.

The first question that any good technical writer will ask is "who is my audience" (actually most writers ask that question). Today, the primary intended user of WordpressMU is an experienced system administrator with software development skills. Any critique of the documentation should probably be done in the context of the intended audience.

In that light, I feel confident in saying that the current existing documentation set is pretty good. Note: In this context the code is also documentation... it is poetry after all.

I am supportive of the idea of starting a project to better organize the documentation for the tool. I agree with Andrea that for the documentation to be useful in the long run, you'll want to make sure it gets incorporated into the official website. If it's good, I'm sure it will be embraced.

To make it good, I suggest that we clearly identify the target audience of the new docs, and make sure that we collect the useful information, and write it in a manner consistent with that target audience.

If the for example the target audience is: "new systems administrators with 1-2 years of windows system admin experience", then the documentation we need to collect is very different than what is currently available. We would need to write out some pretty basic hand holding documentation on setting up a linux server (although wordpress mu runs fine on windows, there are so many basics about the style of WPMU that would be lost on someone without unix experience), etc. That would be a big undertaking, and not something that I've seen most open source (volunteer) projects take on. Hell, I've rarely seen commercial applications that handle that target audience very well.

I'm not trying to throw water on this idea. Instead, I hope these comments will help direct the group into how to go about writing any new documentation the "right" way.

Well, i find your last post helpful. :) Gimme a couple weeks and I actually plan to start writing some docs.

Which is what it really boils down to - someone has to actually write the stuff. :D

I totally agree Andrea... ultimately it comes down to someone deciding that they really want it bad enough, that they want to prioritize it ahead of other things on their list.

Personally, writing docs targeted at an "inexperience windows admin audience" would not be very high on my list. It would be WAY WAY WAY down on my list.

As I said before I think the docs are pretty good.

But if someone is going to complain about the docs, and they decide to do something about fixing it, hopefully they will think long and hard about what they are "trying to fix" before they start.

EDIT: One more thing... in my post a couple posts back, I did not mean to imply that the current documentation was not written the "right" way. I've said it before and I'll say it again... I think the WPMU docs are pretty good for who they were written for; so they were done "right". My reference to writing the "right" way, was intended as cautionary for anyone taking on attempting to do more/new/different documentation.

didn't Php4ever offer to write the docs and let us use it? If he is going through the trouble to write docs for his clients and offer us those docs, can we export it into a wiki on a subdomain of wpmudev?

If this would save Andrea from writing docs that are already being written that would be way cool.

I'd be happy to add some stuff, but most of my info would be more layman's "this is what I had to do" rather than the technical stuff. Heck I could take some of the posts and replies from my last tech issues posted here and fill out a chunk of the documentation that would help most get around the lack of apche / php terminology that stifled me.

And that last paragraph is what would probably be most helpful. :)

I'd be happy with the 'this is what I had to do' style posts.

You know people, all though everything you are saying is essentially true. Its important to keep in mind that many of us are experienced at the very things you mention.

When I made my very regretful angry post I did so because I'm wasn't seeking help as a pro who knows his way around the product but this client who got tossed into an admin position for the community college lost his damn mind when he a NOVICE with WPMU could not find documentation.

Facts are 100% fact. And I challenge anyone here to set me straight because I could use a good ass kickin now and again. but a NEW GUY CANNOT USE THE README.TXT file and successfully setup this product without more advanced knowledge.

I think we as experienced people should maybe find a place to put some quality NOVICE documentation. I get asked unbelievably stupid questions again and again when I just want to tell people Go search. Stuff as simple as HTACCESS and using SSH and BASH installers for bulk version updating. I then realize I'm being a dick and forget that if everyone had our knowledge (you people are included in the our) then there would be no need to hire us.

Documentation, yes, a nice clean repository dedicated to all the crap people ask again and again and again isn't out of line.

I'll help you where ever you ask for help if you decide on this as a project for this forum.

I think everything one needs to know about MU is in the read me, and everything else can be found through wordpress.org. I guess? It IS just WORDPRESS with an MU. You know?

I'd like some things maybe that relate to the multiple blogs part, but I'm getting along fine. And I'm not even a pro or have PHP in my username. I even have stupid moments and post really stupid posts on the boards here. He he. Yet ... don't need much more than I can find SOMEWHERE either on the forums or whatnot.

Maybe the guys at WordPress want to make it clear that MU is for those who know what they're doing, however it isn't that bad. The worst part was asking my host to set up the ability for the script to set up subdomains (I forget what it's called by now), and like 5 mins later whammo there it was. :-)

Good luck!

Wiki? You should read http://mu.wordpress.org/forums/topic.php?id=748&page&replies=12

There are pages on:
http://codex.wordpress.org/index.php?title=Special:Recentchangeslinked&target=Category:WPMU&hideminor=0&days=180&limit=50

I still think that links on both the forum and wpmudev to the above category recent changes page and the category home http://codex.wordpress.org/index.php?title=Category:WPMU would be useful.

I hope this is constructive input. And I hope to contribute by making a screencast of how to install WPMU on cPanel.

But first I need help figuring out where I went wrong.

Background: my cPanel is straight out of the box. I've added no files. I'm using a VPS. PHP 5 and MySQL are latest versions.

Me: I just installed Moodle on another URL using cPanel, which means I can follow directions, modify php files etc, and even troubleshoot a couple hiccups successfully. But I am not an old hand at this. (Using a screencast that walked me through that Moodle install was invaluable, by the way. I want to make one of similar value to users here, to repeat. To see what I mean, here's the Moodle screencast: http://otaru-jc.ac.jp/hagley/
settingupmoodleonhostingwithcpanel.swf)

I have followed the instructions on http://codex.wordpress.org/Using_cPanel

That is, I:

1. Set up the MySQL db and added myself as user
2. Modified the connection string as instructed
3. Modified the wp-config-sample.php file in wpmu 1.2.4 and saved it as wp-config.php
4. Installed wpmu in the root directory on cPanel

According to the instructions above, I should be able to go to mydomain.org/wp-admin/install.php, and see the installation screen.

I don't. I get a "file not found" message.

I have also read the README.txt file with the WPMU 1.2.4 download. It is SO CLOSE to being sufficient for a person at my level, I hope you'll be open to feedback on where it fell short. So here goes:

1. In the Install instructions, steps 1 and 2 are easy. For Step 3, this line is ambiguous:

If you want to integrate WordPress MU into the root of your domain (e.g. http://example.com/), move or upload all the files and directories of the unzipped WordPress MU directory into the root directory of you web server.

--this is ambiguous because it can be taken to mean either a) upload the files into the root directory WITHIN the WordPress MU folder on my harddrive (in which case I'd have root/wordpress_mu/(all the files), OR b) upload the files directly into the root directory, not into the WPMU sub-directory.

I tried both. Neither worked. And yes, I included the wp-config.php file I made with my MySQL db name, username, pw, and "localhost."

So which was the intended meaning?

The next place the README.txt instructions fell short for me was in "Install, Step 4":

Make sure your install directory and the wp-contents directory are writeable by the web-server.

--In cPanel, my wp-contents directory is "755," writeable only by "user". I'm pretty sure that's as it should be, but would think that adding a line or two clarifying how to confirm that would be easy enough to do, and save everyone trouble downstream.

But here is the more vexing question about Step 4: What / where is any "install directory"? I don't see one.

Finally, I installed WPMU in my root directory, followed Step 5 in README.txt by visiting http://(mydomain.org)/index.php, and came up with:

The requested URL /index.php was not found on this server.

So I am stuck here.

I'd also suggest fleshing out the "Apache" instructions in README.txt. I'm not yet advanced enough with WebHost Manager or cPanel to know how to locate these settings. Why not dispel my ignorance about this in README, and those like me? Again, I'll add the steps if necessary.

If anyone will take the trouble to help me unriddle all this, I will gladly delete everything from my cPanel and repeat the correct install on a screencast (and while I realize not everyone uses cPanel, surely this would help the many who do), and share it here.

I'll also volunteer to edit README.txt to make it more dummy-proof for "intermediate dummies" like myself.

cburell: you run a large risk that no one will even see your post as its irrelevant to the subject line.

Perhaps you want to delete the content from here and post as a new thread?

Try this tutorial for cPanel.

It's linked off of Matt's article, pointed to in the readme file for MU.