MT4 Community Documentation Project
From Movable Type
The following started off as a short paragraph in response to a call for project proposals. I'm not sure how it got this long. I suspect alien abduction and ghostwriting.
Either that or the idea stirred up something that I've felt strongly and thought for a very long time. Our community is not strong but I think it can be and I think we have the power to make it so.
Contents |
Putting the User in User Documentation
In my opinion, one of the most important sections of the documentation after the installation section is the template tag reference because it's the translation layer between you and your readers. As Movable Type has become more and more powerful, the template tag reference has lagged behind in its comprehensiveness, completeness and accuracy. Now obviously, I know what it's like and why things are this way and this is no knock against the MT team. But right now, with MT 4 about to hit the public, it's even more important than ever before that the front door of the house is in working order.
Now, lest you think I'm just bitching and moaning and telling you guys to fix it,1 I would actually propose that the BEST way to fix this problem2 is for the MT team to use its position of power at the hub of this community to rally the troops and focus the community itself like a magnifying glass looming over an ant on fixing this one problem.
Out Come the Snipers
That may sound nuts and, in fact, I'm sure you'll have some extremely vocal minority of the ProNet community (and beyond) bitching and moaning about "Well, why should *I* update their docs? That's their job".3
But to those people, I would say: If we use this software and have vested a solid amount of time into it, it naturally goes to follow that we would like the software to be successful enough to continue for as long as we have interest and even become something bigger than it is now. But poor documentation will make a competitor who pales in comparison in terms of feature set look like the 900lb gorilla. Hypothetically speaking of course... It doesn't matter how powerful a piece of software is if no one know about it or is given the key to unlocking that power.
Having worked with Movable Type exclusively for the last six or so years first as a hobbyist, then as a developer, then as an author, then as its Product Manager and now as the technical brains behind what is arguably one of the the best known and respected Movable Type Enterprise consultancy in the world (if not THE one), I know for a fact that there is an ocean of distance between the software's capabilities and even the professional community's general knowledge of it. I am astounded almost on a daily basis when I learn something new about the software that I've probably spent something like nineteen thousand hours on since Ben and Mena first told me about their little project.4
And the number one reason for that IMHO is documentation that has always withered miserably in the shadow of the historically brilliant and mind-blowingly productive engineering team that creates the software.
The Power of an Invested Community
It's an old cliche, but it's so true: You have to strike when the iron is hot.
The Movable Type community has not been as vibrant in years as it is right now and you can expect that to go up at least for some time after launch. With all of that excitement and fervor about Movable Type 4, it's the perfect time for the community to finally rediscover itself in a project that will, more than anyone, benefit themselves.
By my very quick count, there are about 400 template tags, some mysterious number5 of non-global template tag attributes between 141 and 467 and 40 global filter attributes. For a community of our size, if each member simply did their best on one single item per week we'd be finished in less than two weeks.
But I don't believe that even that is the most powerful motivating factor. Instead, I think it's something much more special and powerful: Synergy.
If the entire community could, perhaps for the first time,6 be focused together and unleashed upon a single task -- this single task -- I have utterly zero doubt that we would shock ourselves with our swiftness. We would be awestruck by the sheer number of things we learn. And we would astound ourselves -- today and for long time in the future -- with the final fruits of our labor.
But most importantly, if the level of passion and involvement was high enough and we knew that we were joined by legions of others doing the same thing at the very same moments, it would create a cycle of positive resonance that you could almost feel on the medium in which we worked.
And like a time-lapse film that we know isn't, we would watch the work we've done rise up from the dust in which it has lived in for so long and become an incredible tower of knowledge that we built. Together. As a community.
Given that only a handful of us are within cat-spinning distance of each other and the vast majority of us have never even seen one another's faces, that sort of feeling and the lasting effects it would have on our community are truly unique and priceless.
A community of talented and passionate people each doing just a little to make a lasting difference, but doing so with overwhelming purpose and in concert in an effort to better not Six Apart (although certainly it will) but instead the health and depth of their own knowledge and future experience with the piece of software by which they are connected and clearly invested.
I really, truly, honestly can't think of a better way to begin the MTOS era.
Sincerely,
Jay Allen
Application Architect
Textura Design
Notes
1 - ...which of course is ludicrous given that every time I find a problem, I still go in and fix it. :-)
2 - and perhaps solve a few others inadvertently along the way...
3 - We all know the type...
4 - Those who know my work habits and have a calculator handy will know that that is a ridiculously conservative estimate.
5 - The number is mysterious because unlike template tags and global filters, attributes specific to a particular template tag are not registered anywhere in the system and live completely encapsulated inside its parent tag handler routine. This certainly plays at least some small part in the difficulty of accurately and comprehensively documenting. For those who are interested, I arrived at the number by literally grepping for '$args->{' and then taking that count as well as a count after duplicates had been eliminated. Scientific, eh?
6 - A memorable and bitter email war in ProNet or a brand new beta test are the only other two occasions I can think of when so many in the community are focused on the same thing at one time and neither of those the both positive or collaborative experience that this would be.