Vanilla is a travesty of poor documentation!

brian_k · April 2010

I stumbled upon Vanilla after searching for a, well, a very simple "vanilla" PHP forum implementation. This software, from what I've been able to find from community posts is *EXACTLY* what I need and want to use for my venture startup as a forum code base.

But the documentation for it is not just poor, but either ridiculously non-existent, OR COMPLETELY WRONG. Bugs I can deal with, but for both 1.1.10 and v2 beta installation the documentation is all over the place or STATES THINGS THAT ARE SIMPLY NOT TRUE. I could just move on and look for another forum code base from which to work, but I really want to use Vanilla and would like a response here.

There is no easily visible reference or installation notes for:
1. Platform requirements (Windows? Linux? Apache? IIS?)
2. PHP extensions needed for proper functioning (Didn't even know what "PHP_PDO" or "PHP_PDO_MYSQL" was until I generated errors installing and searched the community here.
3. Common installation errors and how to fix them. I've found solutions to the various on-screen errors by searching the community here for the exact error. How come these are compiled into a simple stickied post for all to see?

The installation instructions found at "http://vanillaforums.org/page/InstallationInstructions" state a simplicity to installation that is, at best, misleading.

"300,000 businesses, brands, and fans". Ok. But extremely hard to believe.

Stash · April 2010

Fancy helping write some been documentation? I know that it would be well received, and I'd be willing to lend a hand.

I would imagine once the RC is released there will be a single discussion that will track feedback on that release quite intensively. However, the main reason there probably hasn't been something like this so far is that there hasn't been a single packaged up released (that I'm aware of).

Thanks for the feedback, but if you could help out that would be the best thing. Even stating specifically where the documentation is "COMPELTELY WRONG" woudl really help in getting it corrected

brian_k · April 2010

Open source. Community supported. I get it. I probably should have been a tad more measured in my post. I'm frustrated because I've searched, installed, and tested several products for the last few days looking for the one that met my needs and Vanilla seems to provide the best balance of configurability and simplicity.

I can help with some of the documentation, but without a working installation of my own yet, the majority of the documentation is likely going to have to come from the programmers who author the software or the people who work with it on a regular basis. I know that documentation is a royal pain and the last thing a programmer wants to do after staring at code all day is tell everyone else what they did or how to do it. But to reach critical mass of installations, it has to be done.

Perhaps this suggestion will help. I think what will help get over the lack of documentation hump would be a sticky'd, post somewhere that only moderators could edit / update and no one could reply to. A single post with references to other forum locations where the answer has been found. Something like this: http://forum.arcadecontrols.com/index.php?topic=19049.0 Then, anywhere you reference installation steps or instructions, be sure to include a link to that post.

The configuration instructions and minimum specs for 1.1.10, however, really... truly... needs to come from you guys unless Vanilla is intended to be used, installed, and run only by the technologically advanced user.

Dykam · April 2010

The current main problem is that Garden is somewhat unstable, and documentation gets outdated by changes. People don't feel like it's worth contributing to something mutating.

Stash · April 2010

@Dykam is right about Garden/Vanilla 2 still mutating. However, you'll be glad to hear that there is something planned for the release of the RC.

As for Vanilla 1, is your dislike of the installation instructions because they're too wordy? The more specific you can be the easier it would be for me to plan improvements

I appreciate your comments on this, because if no one says anything then it just stays as it is...

brian_k · April 2010

My rant, mostly, was directed at the 1.1.10 installation. Figured it fit best in the "feedback" forum.

Stash, I checked your link above and those instructions work for Linux installs or at least a reasonably intelligent Windows admin can translate properly. One of the things that caused me to miss that documentation altogether is because it's listed as "upgrade" instructions. Note the text directly beneath the Download link on your download page:

"Check out our guide to installing Vanilla and you'll be up and running in no time. If you're upgrading from an older installation of Vanilla, we've got instructions for that, too. If you run into any issues while getting set up, visit our forums where our active and friendly community of users and developers volunteer their time to help you out."

A lot of reasonably intelligent people won't make the logical jump to look under "upgrade instructions" for first installation instructions. The "installing Vanilla" link takes you to v2 documentation.

I'd reword it like this:

"If you'd like to jump right into version 2 of Vanilla, check out our (link)guide to installing Vanilla 2 beta(/link) and you'll be up and running in no time. If you'd rather install the current, stable version of Vanilla (v1.1.10) or you are upgrading from an older installation of Vanilla, (link)we've got instructions for that, too(/link). If you run into any issues while getting set up, visit our forums where our active and friendly community of users and developers volunteer their time to help you out."

I'm happy to provide some stub documentation for a Windows install at some point that you can incorporate into that set of instructions page for v1. I just have to figure out the minimum specs first. Does anyone have a definitive list of what PHP extensions have to be enabled?

brian_k · April 2010

For what it's worth. I eventually got Vanilla 1.1.10 up-n-running and I'm "tickled pink". SMF is a pretty powerful system, but is so large and bloated in terms of UI and administrator options that it's more suited for sites who's content is 95% forum. Vanilla will allow me to incorporate forum functionality into a site without taking over the whole damned page.

Stash · April 2010

Glad to hear you actually like it! *laughs*

Have you installed it in IIS? Please do create a Windows install stub, I would be glad to add it to the documentation, and perhaps I can separate out the installation and upgrade instructions to simplify things?

Personally I have installed Vanilla 1 multiple times on Linux (1and1 and Dreamhost hosting) and run my own dev install on Windows Vista + Windows 7 with xampp and I've never had a complaint about PHP extensions.

For Garden/Vanilla2 I wouldn't like to comment on requirements, one of the devs would have to answer that for you, @Mark, @Todd, @Tim?

Tim · April 2010

Hi guys. We've got a Requirements Page in the Documentation section of VF.org and I just updated it a few minutes ago.

Hopefully it answers your questions!

brian_k · April 2010

Thanks Tim.

"some admins disable this, we don't know why". The default installation of PHP 5.2 (for Windoze anyway) doesn't look like it enables any extensions. I think most Windows guys running PHP through IIS ISAPI know where to change this, but there's the chance that they wouldn't know off the top of their head that it needs to be enabled.

Here's my basic recommendations for the documentation page or primary link you have at the top. Whether or not you take them is up to you.
1. Provide an easily identifiable link to the system requirements somewhere near the top of the page.
2. Provide separate sections on that page that split out documentation (or at least make it plainly clear) what documentation is for v1 and what is for v2.
3. Of course it's optional, but the Vanilla platform really needs both v1 and v2 installations instructions for both Windoze and Linux systems.
4. Above all else, ya'll need to elect someone on the dev or support team to take control, be in charge of the single most important document missing from your collection -- "Troubleshooting Installation Problems".

You guys offer a great alternative to the blinding bloatware that has become SMF and other forum implementations that only barely stopped using the marquee tag. If you straighten up or coalesce the documentation, it could mean the difference between the purely techie crowd who installs it and a bigger adoption base.

FWIW

Stash · April 2010

I agree that both V1 and V2 need to have clearly recognisable documentation linked from the homepage of the docs.

Vanilla is a travesty of poor documentation!

Comments