GHOP #87: Create a recipe for a wiki site

subscribing.

Also moving to Documentation queue.

Should I make this as easy as possible (as in use the Wiki Installation Profile) and show people how to set that up to work smoothly, or start from scratch with a default Drupal 5.5 site?

Here are all of the screenshots I've taken and edited down to size. I plan to write the copy today. I also attached a shell script (assuming the user is on Linux) that will make setting up the Install Profile (as per the readme.txt file included in it) easier. I will put links to each of the modules in the final copy, however, this is the method that the screenshots support.

I have a few concerns about that profile (other than the fact that it doesn't appear to be maintained.) One is that it is counting on an older version of pathauto that is missing the token requirement so you'll need to make sure you highlight that in the instructions and get the newer pathauto with token installed. I'm also not a big fan of encouraging people to patch a contributed module - bad, bad, bad. Also since the profile is not maintained are we sure that the patch is still needed? Was it submitted to the project issue queue and rolled in? Has the code changed enough that the patch won't work anyway? These are the kinds of things that are just ripe to screw people up even if they have instructions to follow. Rather than requiring people to patch for images, I'd just go with something else entirely (like IMCE) but obviously that then falls out of the scope of using the profile.

Overall I'm not a fan of the profile, but the task didn't say *how* to do it so I wouldn't ding you for that at all. I've said my piece and will leave the discussion to Crell.

I understand your concern. Before I even started taking screenshots, I tested most of the site it creates (although I didn't notice the token one). The solution I have thought of now (and anyone who has advice - by all means, I'm willing to take it!) is to attempt to break down what the install profile does into seperate elements in a (clearly labeled) "Advanced Users" section of the recipie. I was wary about doing that though, because the amount of steps could easily double from the twenty-one that it is now. This may put off anyone who is thinking of integrating a Wiki into their site to use other software (even for people who consider themselves advanced).

I'm not sure that using the installation profile is such a great idea either, especially if it's not maintained. You can write a shell script to help automate the downloading of modules required for an installation profile (I actually have one for a different profile at http://drupal.org/node/199369), but for users without shell access or using Windows without cygwin, a shell script probably won't be very useful. Note that many shared hosting accounts do not include shell access, and my guess is that many also don't include cvs (the host one of my sites sits on would install cvs if I asked, but it's not there by default, and shell access is not given by default either).

As add1sun said, the task doesn't specify how you should do this, so whatever you decide is fine.

I have decided to do the following:

• Have two sections - Easy and Advanced
• Easy:
• The easy section will have directions including the Wiki Install Profile, with a warning that is is no longer maintained and is not recommended
• This will be for people who want to just get a wiki site now and are able to follow the directions in full.
• Advanced:
• Include full directions on how to setup everything without using that install profile or shell script
• This is for people who want a fully functional wiki site and don't want to worry about the profile no longer being maintained. This is also for people who (as aclight mentioned) do not have the abilities required to use shell scripts or use cvs.

Hopefully, this is the last set of screenshots I'll have to take (with the above plan, I needed a lot more. As there are now over fifty screenshots, I won't be using them all. However, I figured that it's better to have more than you need and eliminate a few then find out halfway through that you need more.

Makes sense. I wasn't too sure how to get it done, but this clears it up extensively.

It's done. The file (and accompanying screenshots) are tar'd and gzip'd. Any recommendations?

Marking as needs review.

1. Step 1 needs a period at the end.
2. Step 2: I would specify what the modules directory should be (usually sites/default/modules) and would say to download and untar the following modules with a link to a drupal handbook page describing how to do this (I imagine there is one already).
3. Step 4: Is PEAR something that always comes with PHP? If not, you might indicate that it needs to be installed if it has not been already and include a link to a site describing how to do this (assuming there is one). Also, fix the modules directory here to match what you use in step 2, assuming you change it there.
4. Step 6: What modules?
5. Step 7: Give the menu path to create a content type. Also, the red box for promoted to the front page is confusing. Users won't see this in red, so either explain or make it the same color as the other boxes.
6. Step 8: A link to how to create a role or what a role is would be nice. You should specify the menu path to Access Control.
7. Step 11: "(courtesy Wikipedia) " should be "(courtesy of Wikipedia) ".

There are a few other places where giving the Drupal menu path would be helpful, so just read through your instructions and add that in where appropriate.

Make sure to follow the Handbook style guidelines at http://drupal.org/node/22299

With regards to your wiki content type, don't you want to also make this node type automatically create a revision any time it is edited?

I think this overall looks very good.

Gaaah. Due to some school stuff, I have not had a chance to remedy these problems. I will try to work on it this weekend.

I have addressed all of the issues aclight and crell made in comments 14-15. I also removed the screenshots that aren't used from the archive.

In step 6, you say to use the name "Moderator", but the picture has "moderator". Also, for that email address (and all others) you should use example.com as the domain.

Otherwise this looks good. Go ahead and create the handbook page for this. For the pictures, create an issue in the documentation queue and upload all of your images there. From your handbook page you can then reference those image files, though unless you are a documentation maintainer, the image tags won't actually do anything. You can either apply to be a documentation maintainer or just let us know here when you're done and one of us will fix it up.

It's here. The links to the images showed up as attachments that worked, so I didn't bother creating the issue. Another thing - Is the text supposed to be setup strangely like that? It didn't show in the preview, some I'm wondering if it's some CSS style that's being applied to book pages.

The reason we recommend creating an issue is so that the handbook page doesn't have the images attached at the bottom of it. It will work the way you've done it, but it's not quite as clean. And if you had lots of images, it would look cluttered.

BTW, it will also be nice if in the HTML text that creates the handbook page you added line breaks so that it's easier to edit it later.

It did have line breaks, but that was causing those weired wrapping issues I spoke of in comment #19, so I took them out. I suspect this is because of the way Drupal automatically creates line breaks in content. The Issue is here.

Hm...I'm not sure about the weird wrapping issues you're reporting. I notice that your HTML includes <div> tags, which are not allowed in filtered HTML, so I would remove those. You can also remove <br /> tags, and replace those with line breaks, as the line break filter will add the br tags.

I fixed it.

@ aclight, re: #20, just so you know, there is no problem uploading the images to the handbook page. It keeps it a little better organized that way actually. Once you upload the images you simply need to uncheck the "List" box for each attachment and then the list won't show at the bottom of the page.

Ok, looks good to me. I fixed the handbook page to display the images. If you find something you need to edit later you'll just want to apply to be a documentation maintainer and then you'll be able to edit it. Great job!