Steamed Puddings

I’ve been enjoying some beautiful growth at the site recently.  I made blogosphere friends (hi, ladies!) and I like how we banter back and forth between our blogs with lots of comments.  The key to a comment conversation (commversation?) is to know when someone has responded to what you wrote regardless of what blog you wrote it on.

Most of my friends are running their blogs on Google’s Blogspot site which provides free hosting and the Blogger engine.  It’s a great setup; I used to use it before I switched over to Movable Type 3.X in late 2003.  Blogger is nice because it generates a feed of the comments on an entry.  You already know all about feeds, right?  Perhaps you’ve subscribed to this blog using a feed reader?  If not, read this overview of feeds.

Anyway, the point of a feed of a blog entry’s comments is to notify you when someone else (perhaps the blog owner, or another friend) comments on the same entry you just wrote something on – without you having to keep revisiting the site and trying to remember which entries you were commenting on in the first place.  This is how it works (hopefully written in “mom” so youse can follow it easy-peasy):

• You write your comment (or maybe you just want to keep up with other people’s comments).
• When you’re looking at the page that only contains the entry and comments (not the main page), you click something like “Subscribe to Post Comments (Atom)” at the bottom of the comment list.
• Your feed reader takes over and confirms that you want to subscribe.  This part of the process is different for everyone.
• Voila!  When a new comment is posted, you see it in your feeds.  Again, if this is all incomprehensible to you, read a bit about feeds and feed readers first.

Back to the story: so far, you understand that feeds of blog entry comments are good things.  My blog software (Movable Type) has just released a brand new version – you might remember that from my reboot of the site design in early July.  Unfortunately this new version has a few drawbacks: its template structure (which I understood well in the old version) is now incomprehensible to me, and it doesn’t offer comment feeds by default.  I could modify the templates myself to generate these feeds, but I don’t quite know how to do it.  I need documentation.

The documentation for Movable Type 4 is really lacking.  There’s a bit of general doc on the MT.org website, touted as the new community destination for MT information.  Supposedly users can contribute to the MT.org site by commenting on the existing articles/docs.  In practice this doesn’t work so well – I’ve written a handful of comments and none of them have been published on the site.  There’s a new wiki for MT, but it’s mostly empty, probably because it’s not publicized anywhere on the MT.org site.  Some old documentation for Movable Type 3 is still on the MT.com site, but it’s mostly useless for the new template structure in MT4.  There were some extremely useful forums I used a lot during my life
with Movable Type 3.  If they still exist, they’re also not linked to
from anywhere.  Sigh.  Have I confused you yet?  Can you see my plight?  I want a known, publicized, well-used place to find GOOD documentation for MT4 and to contribute and ask questions.  This doesn’t seem to exist yet.

I wrote the following on the talk page for the new MT wiki:

I’m really confused about the purpose of this wiki, and the state of
MT documentation in general. MT3 had the online knowledgebase (though
it was hard to navigate, easy to search) and the excellent forums. Now
that MT4 has been released, the MT.org site has a small amount of very
general documentation and says that user contributed notes make the
documentation better. I’ve tried to comment on the MT.org site several
times to ask about further topics for documentation and have never seen
any of my comments published. It’s as if MT is discouraging the MT.org
site as a place for users to discuss the software and provide further
documentation.

I think this wiki would be a great location for
user-contributed documentation and could also be the new home of the MT
Knowledge Base (currently at MT.com and not containing information
specific to MT4). However, the main page of the wiki contains
information about plugins and MT performance. This doesn’t make it seem
like this wiki is meant to be the go-to site for user documentation.
What is its purpose? If it’s here for us to fill with documentation,
could it be advertised more widely on MT.org?

What about the role of the forums that were so incredibly
useful during my time with MT3? Do the forums still exist? Why aren’t
they linked from the MT.org documentation pages?

I’ve been using MT for about four years. I’m not a novice, but
I’m certainly not an expert, and the new template structure of MT4 has
me confused. I’d like a place where I can find more information not
just about what the tags are, but about why they’re in their current
locations in the templates, and how the templates interrelate. What’s
the most logical place for this information to exist?

Kelly 21:08, 24 August 2007 (PDT)

I want to raise this issue with the entire Movable Type community.  I played an active part in the beta process for the new Movable Type 4 and I submitted many, many bugs and feature requests.  I love the software, which is very powerful, but I’m extremely dissatisfied with the almost-total lack of a concerted documentation effort for it.  Jay Allen, in a section of the new MT wiki, makes this same call – for user-created documentation – but so far it just doesn’t exist.

Anil Dash (part of Six Apart, the company that makes Movable Type – which I should point out is a FREE SOFTWARE PRODUCT) said this about MT4 documentation:

“The best documentation in the business. MT4’s
documentation has been rewritten from the ground up to focus on the
tasks you have at hand. And the Six Apart Guide to Business Blogging is
over 75 printed pages of information on how to help your company make the most of blogging.”

I’m sorry, Anil, but I just don’t see the depth in the rewritten documentation.  There’s a lot of very basic information but there’s no meat on those bones yet.  The lack of quick comment posting on MT.org prevents users like me from adding that meat.  We need a more appropriate place to generate docs.

I’d like to propose a way forward.  I suggest that Six Apart merge their existing MT.org/docs content into wiki.MT.org to give it a skeleton structure, and then turn the users loose on the wiki.  Novice users finding that wiki today won’t stay or contribute because there’s no clear plan of where the information they want could even go.  I (for one) am not prepared to outline all of the documentation for a piece of software – but if someone more experienced with MT or affiliated with 6A could do that, and publicize the wiki to the entire MT community, then users would be in a better place to contribute and ask questions.

I can even see future job opportunities in this…I do like writing documentation.