Our positive experience with having our support site be basic HTML

April 29, 2022

About a decade ago, we wound up caught in a wiki trap, where our support site was stuck using what had become an unsupported piece of wiki software with an unsupported wikitext dialect and no automated migration path. Our way out was not a different wiki software but instead to scrape the HTML of the existing site and then redo the entire site as plain HTML. You might wonder how that has worked out for us over the time since and if we regret our decision. The short answer is that it seems to have worked well, but there are probably some specific circumstances involved.

Since the initial brute force conversion, the site has gone through one reskinning and simplification of its design. On the server, the pages are all static files; the redesigned site uses a tiny bit of Javascript (and jQuery) to inject a site-wide navigation bar on every page, because that way the navigation lives in only a single file for the entire site. When we need to update something we use our editor of choice, usually vi(m). When we make new pages, I think people generally copy an existing page and then gut the contents in order to leave only the standard structure. We don't try for semantic HTML or anything like that.

(I wrote a bit more about this in my entry on the appeal of using plain HTML pages.)

This approach has been quite successful for us, but I feel there are specific local reasons for that. Two of them are that we don't have much content and we don't change it much. Our overall systems and how people use them don't change radically very often, so our support site needs very few updates. Some of the lack of change is because we know we can't do a good job of keeping very specific instructions up to date, so we mostly don't write them in the first place. People with more capacity to keep documentation up to date might have beautiful specific instructions on how to do all sorts of things on every client operating system they support, with lots of screenshots; we don't even try.

(We can sort of get away with this on the grounds that we're a computer science department so most of our users ought to be able to figure things out on their own. If they can't, we have some people who are there to help them.)

We also have a very small number of people editing the HTML, and we're in a single group. If there were different people editing different sections of our support site, it would be easy for the HTML and style of different pages to drift apart, and we might have to try to write some sort of style guide, and that way lies at least problems. (And we're all familiar with HTML already so there's no learning curve.)

If we were in the same wiki(text) trap today, one obvious question is if we would or should opt for a static site generator instead of raw HTML. If the (wiki) content was already in Markdown, perhaps the answer would be yes, but otherwise I don't think we'd have been very attracted by the idea of scraping the HTML, turning it into Markdown somehow, and setting up a new wiki-like thing when we'd already been burned by one. Writing in Markdown with a static site generator is obvious but I'm not sure it would get us any better results than we've wound up with. And it definitely would make changing the site more complicated.

(As for the appeal of Markdown versus HTML, I stand by my old entry on the varying appeal of wikitext and other simple markup. As a pragmatic matter, HTML is right for us until the point where we're all commonly using Markdown for other things.)

Written on 29 April 2022.
« The practical problem with /etc/pam.d on long-lived Linux systems
Some thoughts about your (our) site needing Javascript »

Page tools: View Source, Add Comment.
Login: Password:
Atom Syndication: Recent Comments.

Last modified: Fri Apr 29 22:41:04 2022
This dinky wiki is brought to you by the Insane Hackers Guild, Python sub-branch.