Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#1 2009-01-24 21:56:27

Plugin Author
From: Neubeuern, Germany
Registered: 2004-11-05
Posts: 519

[wiki] TextBook-Type and TextBook-Audience - Reference or Manual/Guide?

Discussing matters of presenting information in two other threads (textual and visual) a very basic question regarding TextBook arose:

What is TextBook?
Is it a reference – or is it a manual?

Maybe it is not per se evident what the difference is (and if there is any), so I’ll try to make it more clear – carving out the “type’s” characteristics, not yet saying, TextBook is or should be so or so:

  • lists information extensively,
  • trying to cover every “thing”
  • possibly in “many brief articles” (words from Wikipedia),
  • breaking info down to smallest meaningful units
  • easy to look up or, as it says, “refer to”, e.g. alphabetic order
  • users already have a fundamental knowledge of what to look up.
  • flat hierarchy and no weighting of items – save as a subordinate information (like saying “deprecated” to outdated elements).
  • normally lots of pages
  • Normally you do not “read” a reference as a book from the beginning to the end, but simply choose the parts you need at the moment.
  • Teaching of concepts, strategies or workflow is not the common content of references.
  • guides you to make the best of the tools you have.
  • can be lean, just giving you the key capabilities, and leaving the rest to other books, or it can be big, leading you into every aspect, giving instructions and also showing some “tricks”.
  • Chapters, “Basics” articles, maybe tutorials, longer articles dealing with concepts
  • deals with bigger coherences
  • orientation not as “look up” but as “overview”, topic order
  • supposes that users at first have no or little fundamental knowledge, of what to do (or better how to do something). Its task is to give that fundamental knowledge. For that reason a manual often is called “Instruction manual”, “Online help” or “User Guide”.
  • Hierarchical and weighted presentation of information. Topic based.
  • extent based on task and audience
  • A good manual at least has a part, that will be read in context. Normally there should be hints what a reader can leave out if he already knows.
  • A good manual will give you a fundamental impression of the basic concepts and thoughts of your software tool, it will work out the building blocks, it will lead you developing the best strategies (I speak of a good one!) for working and will demonstrate you a sophisticated yet easy to follow workflow.
Both – reference and manual – reflect each an essential task of documentation. Whereas
  • a reference’s structure is more dependent on its subject or topic,
  • a manual’s structure is more dependent on its audience.

A book can be one of the two types – or – a mix of both.

Now to TextBook:

Is it (or should it be) a reference – listing bits of in-depth information to look up for people who are more or less intimate with cms-webpublishing?
Or is it (respectively should it be) a manual/guide – which will introduce a (to be defined) audience into the key benefits of Textpattern and into the Textpattern-Way of doing things, guiding them to develop a clean cms-webpublishing?
Or is it (should it be) both kinds of documentation?
This open definition is finely (but also with danger of some mistake) reflected by the links to TextBook:
On textpattern.com it is linked as “TextBook, the community-powered user manual”, in the forum it is linked as the “Community-powered Textpattern reference”. Both make pefectly sense.

And this also rises the question, which audience is intended.

Because the online audience is a really wide one – and because I think Textpatterns success will be best serving a broad range of needs – in my opinion TextBook should be capable to serve both needs:
  • A community-powered reference as well
  • as a community-powered friendly and instructive manual, which will present Textpattern’s key benefits to a wide audience (or to different audiences by delivering appropriate parts).

Serving different needs but can be difficult and at least needs a good plan.
I’d like to discuss the different approaches for TextBook and its different parts.

If doing both, I think it is essential to agree, in which parts TextBook is a reference and where it is a manual/guide. Or at least where one of those types is prevalent. If contributors with different approaches would work on the same page without an agreement this obviously wouldn’t be easy: writing, reviewing and editing a page from the view of a reference is quite different from the view as a manual/guide.
On the other hand clear concepts and divisions could help making editing more easy. It’s more difficult to write documentation texts if you’re undecided if it should be a reference or if it should be a guide.

An example:
Working on the content panels in my view they are much more of the type “manual/guide”. And I tried to combine reference and guide in these panels: A full reference of widgets but at the same time a guide which shows the “leitmotifs” and basic concepts.
Take for example the right column of the “Write”-panel:
A “reference” approach would break them down to six single widgets, simply describing them one by one, but failing to mark the concept of that group of widgets in the right column.
A “manual/guide” approach first tries to get the basic task of that column as “publishing controls” (and here a name for it has to be found first). Thus it will give new users(admins) a map like the main roads of a town.
The same guide approach takes place in describing the “building blocks” of textpattern.
Whereas the Tag-Reference of course is a pure reference.

Should we proceed to a more worked out concept of reference here and manual/guide there – and perhaps even mark that for readers, so they know what they can expect?

Just a few thoughts, I’d be glad to hear what the others here say.

Last edited by saccade (2009-01-24 21:59:07)


#2 2009-01-27 11:59:44

From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,856

Re: [wiki] TextBook-Type and TextBook-Audience - Reference or Manual/Guide?

Very thorough, as always, and as always it helps to look back on history to avoid reinventing the square wheel.

Short Answer:

It’s mores suited to being a reference, but it’s expected certain concepts will need more explanation. It should not be a flat-out “textbook” as ironic as that term is.

Long Answer:

Long-timers may remember when TextBook was first created and the structure it started off having. The birthing thread was in fact called User Manual (Dec 2004), which should give you indication of the original concept. The content structure was indeed conceived to be written like a series of chapters, so that a user could begin at the beginning and read through to whatever stage they wanted. Not unlike how most people use printed books. However, it wasn’t long before the manual approach failed. Looking back on it all, it failed for the following reasons (by the way, this is only a focus on the English content; translation efforts are a whole different can of worms):

  1. The concept of using a wiki at all for user-generated docs was still new for a lot of people and they just didn’t — or didn’t want — to get it. You’d often hear, “It’s about Txp so it should be created using Txp” or similar crap reasoning. People were — and often still are — locked in the blog mentality.
  2. Txp was still budding, and users were still learning, so few could yet write about Txp effectively. (Devs and plugin coders, the people who knew most about Txp, were busy developing. Not many others had the insight to write documentation, and certainly not for a manual, which requires greater discipline, compounded by the collaborative nature.)
  3. Lack of experience with MediaWiki to use it effectively. (I’ve since worked on many MW wikis and IA projects, and learned a thing or two. I’m trying to fold that back into TxB today.
  4. Users were extremely hungry for short, quick-help like tutorials. Nobody wanted to read theory and background. This was often expressed in the forum.
  5. There were not enough contributors to support a manual approach. To do that model effectively you need a dedicated editor, that was never realistic in our community. Still isn’t (though I think that would really go miles).
  6. Contributor lack of understanding about:
    • target audience
    • writing styles and voice
    • English language
    • wiki content ownership

The sub-items in that last one are problems inherent in any wiki project. It’s fair to say though hearts are in the right place, the skills and/or understanding of what is needed are often not. Yet we take contributions of all kind because contributors are hard to come by at all. For other wiki projects it’s not as much a problem if they have many editors, etc, but for TxB it’s more of an issue. No one is regularly policing content. Editing gets done on a grand scale (when enough people have cried) at long intervals (like now) as opposed to people watching their pages and editing them on a regular basis.

That last sub-item, content ownership, is no insignificant problem unto itself. Sometimes people treat the wiki as if it’s their own weblog; adding a page, putting their name on the article and growling if anyone touches it. That’s not what a wiki is about, as clearly indicated in the interface whenever you’re in editing mode: Attention: All contributions to Textbook are considered released under the GNU Free Documentation License 1.2. If you don’t want your writing edited mercilessly and redistributed at will, then don’t submit it here. I fully believe in that message, 150%.

It’s dead simple, but extremely hard for people to understand: No matter how good you think you have written something, somebody else has the right to come along and make changes. That doesn’t mean they should if your copy is truly better, but it’s possible any copy can be edited to be more clear and concise. (This might include changing how the images are used and referred to. :] ) Ultimately, a given version will appeal to the most people and that’s where the bulk of the changes stop. After that it’s just updating facts as Txp development evolves.

Anyway, getting back to the point, history has shown that overly explanatory copy as typical of a “manual” is the wrong approach. It’s wrong for all the reasons I’ve pointed out above, as witnessed from TxB history.

That said, there is a place for more explanatory content, and it could be in the wiki under certain contexts, ideally in intro sections, but the manual model itself isn’t going to work as long as the problems noted earlier remain; the wiki must be something more referential in structure and style. This is not something you can force either. It’s an organic process that must be nudged and shaped as people make contributions. Keep the writing simple, concise and accurate and everything else will work itself out.

In my opinion, the wiki is beginning to really take shape, probably for the first time in its existence. This comes using the wiki itself more effectively, and from seeing greater contributions recently like those from Els, Bloke, you and myself who have taken active, hands-on interest in rewriting copy that was originally too verbose and complex.

Last edited by Destry (2009-01-27 12:05:10)


Board footer

Powered by FluxBB