Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
[wiki] FAQs: becoming an impressive resource...
Factoid: Several months back, I forget exactly, zem contacted me with a short email (two sentences) saying he “heard a rumor that I was starting an FAQ” and wanted to know if it was true. I told him no, but that it was a good idea, and then waxed on at great length (a bad habit of mine) about how it would be good to develop in the wiki, why it would be good to do so (avoiding yet another documentation platform, community involvement, etc.), etc.. Zem never bothered to reply, and a short time later the FAQ appeared where it is now (let the behavior dictate the tools indeed).
Back to the present:
Although I still don’t think multiple docs sites is good for new users (been there, done that, we move on), I do think the FAQ is really shaping up to be an impressive resource. I’m amazed the developers find the time to develop and write documentation too. (Sharp stick alert: No wonder zem_contact is still v 0.6 — ;)
(Irony aside, I’m not attacking zem, in case y’all can’t figure that out.)
As I watch the FAQ grow and address more of the kinds of questions that repeatedly show up in the form, it becomes very clear that the FAQ is filling a void that has been missing for the community all along — The short answer solutions. (The Forum fails to do it because of it’s excessive noise and disorganization.) I’m finding myself using the FAQ more and more now. Whether by dictation of natural behavior or power of authority, we have the FAQ and it’s truly starting to look like a good and valuable resource.
I do have a couple observations I would like to share.
- From a usability standpoint, I think the FAQ can be a bit hard to read with respect to default font size, disctinction of code from regular text (some code is highlighted, some isn’t), and perhaps line height and paragraph spacing could increase a bit more in proportion.
- Although short answer solutions are good in many respects, they’re not good for all users and all situations, especially for new users. For example (and process this loosely), indicating a tag and its syntax for general instances of use is a good starting point for people (and perhaps finishing point if you are a designer/developer type), but new users will likely need more context than that, they will likely need to have some robust examples for various situations, case studies of use. In that respect, the FAQ is not an end all resource, and something like TextBook can takeover by expanding on the ideas and providing robust explanations. I would hope that the dev team would be open-minded enough to link to TextBook pages where such concepts are expanded upon, when they are. (With this new model in mind, it might be easier to write TxB pages now with that contextual expansion as a goal.)
Note: From hereon TextBook pages will adopt the practice of linking to the FAQ where subject matter is similar. To do it in an orderly way, TextBook will follow a new page-level “References” methodology for all kinds of external resources (using the Chicago Manual of Style’s recommendation for Web content). See page placement and format example here.
Other than that, I would have to consider (by way of history, location, and platform choice) the FAQ … here it comes … is the official documentation resource, and the devs are doing a good job. Bravo.
Offline