Writing About Textpattern

29 January 06

What newcomers to Textpattern can expect with regard to documentation.

Since publishing the first article, Understanding Textpattern Building Blocks, of my anticipated two article series on Textpattern building blocks, I have been contacted a number of times about the possibility of producing a single document that explains how to build a basic Textpattern site. Although I can appreciate people’s frustrations here, a single article about building a Web site based on Textpattern is a tall order, for a couple of reasons.

First, there is no one way to build a Textpattern site, even a basic one, so any attempt to write an end-to-end process like such is not really practical as it could lead people astray from what they may really want to achieve. For example, one article might appeal to a certain audience with Weblog needs, but another group of people might want something entirely different, like a photoblog or a business site. The bottom line is you can’t write a single article that would be general enough for all interests yet still cover complete site design.

Second, and despite the first, producing such an article would require three assets if the article was to have real worth: 1) it would require a writer with in-depth understanding of Textpattern to ensure the most fundamental, core concepts were communicated, 2) the writer would need to have a LOT of time on her/his hands, and 3) the writer must know how to write well and with respect to a given target audience. All of these assets are huge, and while many in the Textpattern community may have a couple of them (though certainly not the same two), very few (perhaps none) actually have all three.

Note: What the Textpattern community does have is a fair number of designers and developers, like myself, who know how to build a variety of Textpattern sites, which for them is often much easier than writing about how to do it. Hence, for a negotiated fee you can have a Textpattern site built for you, with accompanying user documentation, which will likely be better for you in the end, or at least get you to the end much quicker.

In fairness to the many folks out there who have written on behalf of Textpattern, there is lots of good information available that can help guide a newcomer through the basic steps of site creation. To be sure, there isn’t a single document that says it all, but rather many articles covering many facets of Textpattern. In addition to the three authoritative documentation sources I’ve mentioned before—again, the Textpattern Support Forum, the Textpattern FAQ, and TextBook—there is also the Textpattern Resources site, which for the most part is a search portal for various Textpattern articles posted on Weblogs around the world. If one spends enough time hunting, they’ll be able to put many pieces of the Textpattern puzzle together.

With that last thought in mind, one thing an aspiring writer for Textpattern could do is attempt to write an outline of the steps required to build a given site type, where insteading of filling in all the sectional details themselves, they simply provide a short list of links for any given section topic that points to the best existing articles available on the subject. Developing a complete walk-through document in such a manner would achieve a number of things:

  • It would be somewhat easier to prepare (theoretically) should any writer take up the activity.
  • It would provide the 1-2-3 instructions in context to the process that a single article would provide.
  • It would save newcomers having to conduct time-consuming searches for disparate articles on their own.
  • It would lay significant foundation for the writer (or perhaps another) to produce a complete, concise and consistantly written article later, for which there is seemingly still great demand for.

As I sit here and reflect on this, the obvious response comes up: start such an outline in TextBook. In fact, that road has been tried before and didn’t get very far. The problem there, is that it relies on the whims of the community, and as TextBook has proven, contributions of any kind are slow in coming. No, to be sure, what an effort like this would require is a single, good writer who has the necessary time, insight and focused dedication to put such a document together.

Note: As you come to perhaps know Textpattern better, please consider making your own contributions to TextBook. No one person will ever be able to write everything about Texpattern. Good documentation will eventually be realized by the collective efforts of the user community, and that means you as much as the next person.

My advice for newcomers to Textpattern is to make use of the authoritative resources I mentioned before, start your own document collecting activities as you need for the given site functions and features you desire to have (printing articles and keeping them in a notebook is one very effective method), and tinker with things on your own. If you are not too concerned with having a custom interface or custom functionality, you might consider using one of the growing number of Textpattern themes (or skins) that are available, each of which should come with it’s own limited set of instructions for getting it implemented. A good place to look for the available themes is TextGarden. Otherwise, one must resign themselves to a little patience as existing documentation resources like TextBook gradually improve, and they certainly will.

Having said all that, however, I will be writing individual articles from time to time that are meant to build upon one another conceptually, and you can consider Understanding Textpattern Building Blocks as the first of that effort. The next article in the building block series, Textpattern Building Block Mechanics, will be published soon. Stay tuned.