I’ve been hanging out on the dasBlog developers’ mailing list for the last couple of months, and I’ve made some minor con­tri­bu­tions to the code.

I sent the following email to the developers’ list last night.

My wife has decided to start a blog for Team Ireland in the 2006 Knitting Olympics, and she asked me to install dasBlog on her site. I decided that this was an excellent op­por­tu­ni­ty to do some usability testing on the in­stal­la­tion in­struc­tions for dasBlog. I asked her to try installing dasBlog, while I watched. I promised that I would bail her out if she got mired too deeply.

Emma has worked as a black-box software tester for several years. She writes SQL scripts by hand, but is not otherwise a programmer. I figured that she could probably install a project like dasBlog, with an intended audience of Advanced End Users.

First, we obtained a graphical FTP client (FileZilla) and checked that she could suc­cess­ful­ly upload a one-line ASP.NET program to her website:

The time is <% = DateTime.Now %>

Then it was time to start installing dasBlog. I told her to start at http://dasblog.info and figure out how to get dasBlog and how to install it.

She totally ignored the al­pha­bet­i­cal table of contents on the left-hand side, which is formatted as a rather large set of RSS feeds. Instead, she read through the long blogpost on the right-hand side, which didn’t enlighten her. After a while, I pointed to the left column. Her reaction: why do I want to subscribe to feeds? I pointed out to the Install/Setup feed. (Reviewing the frontpage post now, I see that the Install/Setup link also appears there.)

There needs to be a prominent link on the front page to a Getting Started guide. http://dasblog.info and http://dasblog.us are a huge im­prove­ment on the state of the doc­u­men­ta­tion a couple of months ago, but they still need work.

She found the Install/Setup in­struc­tions confusing. They don’t cover well the case of doing a remote install to a commercial host provider. Obviously, it’s not possible to write a com­pre­hen­sive guide on this, as providers have many different con­fig­u­ra­tion utilities. Our provider is using Ensim’s WEBp­pli­ance, which I find painful to use.

There needs to be a Point #0 on the Install/Setup in­struc­tions: download the files. After some more head­scratch­ing, she found her way to the download page. She was pretty sure that she didn’t want to download DasBlog-1.8.5223.2-Source.zip, but she wasn’t too sure if she should download DasBlog-1.8.5223.2-Web-Files.zip.

She created a local directory, C:\dasblogce and unzipped the files there. That of course meant that the files she needed to upload were in C:\das­blogce\­das­blogce.

Point #1 of Setup/Install is unhelpful to the unini­ti­at­ed. Point #2 isn’t all that clear either.

Using FileZilla, she uploaded the files from C:\das­blogce\­das­blogce to \inet­pub­\www­root\­das­blogce on her server. Then, with some help from me, she figured out enough of the horrible Ensim interface to create a virtual directory, TeamIre­land, pointing to the dasblogce folder.

At this point, we went to http://thewheel.biz/TeamIre­land but we weren’t able to get in. We got some fairly unfriendly ASP.NET errors. I had to wade through the Ensim UI and grant write access to the content, siteconfig, and logs sub­di­rec­to­ries, per the Install page.

Finally, we saw the default page provided by dasBlog!

She had read enough of the Install in­struc­tions earlier to know that she needed to modify site.config and siteSe­cu­ri­ty.config, but she wasn’t sure how to modify them on the server. I suggested modifying the local copies and uploading them.

Her first reaction on seeing site.config was that there needs to be some paragraphs (blank lines) for read­abil­i­ty. She nearly overlooked the <Root> setting, but got that configured correctly.

The default in­stal­la­tion of site.config needs some comments. The stuff that you really have to modify should be in a clearly delimited block at the top. Something like this:

:

<!-- Modify this section before installing -->

<!-- Important: set this to the base URL of this blog, such as
     http://example com/joeuser/blog/ -->
<Root>http://localhost/DasBlog/</Root>
<!-- Banner text. (Note: not all themes show the Subtitle or Description.) -->
<Title>My DasBlog!</Title>
<Subtitle>newtelligence powered</Subtitle>
<Description>A blog about my interests: computers, games, beer, etc.</Description>
<!-- Email address of blog adminstrator -->
<Contact>dasblog@example.com</Contact>
<Copyright>Your Name Here</Copyright>
<!-- Default visual theme -->
<Theme>dasBlog</Theme>
<!-- End of essential modifications -->

She was less sure what to do with siteSe­cu­ri­ty.config. She thought she needed to use the same Name and Password as she uses to log in to the server. (No. It’s arbitrary.) She also needed to add a few additional Users, since it’s going to be a group blog.

There should be a commented-out example of a con­trib­u­tor user in siteSe­cu­ri­ty.config:

<!-- example of a non-administrator user
  <User>
    <Name>SomeOtherUser</Name>
    <Password>blog-password</Password>
    <Role>contributor</Role>
    <Ask>true</Ask>
    <DisplayName>Some Other User</DisplayName>
    <EmailAddress>SomeOther@example.com</EmailAddress>
  </User>
-->

She uploaded the modified site.config and siteSe­cu­ri­ty.config. It failed horribly when she went to log in. I had to download the events.log file to realize that she had deleted the </Users> in siteSe­cu­ri­ty.config.

That fixed, she was able finally log in and create a post. I won’t detail the pain we went through to upload images via Free­TextBox.

The dasBlog admin interface has not been working for her. It’s unable to write to the siteconfig directory. At some point last night, the content directory somehow became unreadable and the site started throwing ASP.NET errors.

I was able to fix that tonight by blowing away the content directory in FileZilla and uploading a backup. I think I’ve fixed everything, by explicitly granting read and write to the siteconfig and content di­rec­to­ries and everything contained therein.

Epilogue: Every new entry in the TeamIre­land blog is being created with the wrong per­mis­sions, causing dasBlog to puke. It can be fixed by setting the per­mis­sions for each new file to read/write through the Ensim interface, but it’s hardly a good experience for a group blog. I’m still waiting for iHostSites‘ support people to set the ACLs properly.