[wiki] User Manual

alexandra · 2004-12-26 20:03:21

Hie,

i did not read the whole thread, sorry but i guess, i got the idea and intentions.

Right now i am all confused about the various docu efforts. There is Alicsons textpattern.org and a TextBook on textpattern.net and some personal blogs (kursor, morton) with a lot of stuff, there was a Wiki, which was canceled a while ago…

Looking at this through the eyes of an foreigner and beginner one has to get confused.

I am no great Wiki user so i set up a txp blog which contains txp stuff and links in german, my nativ language. As well i started transferring Alicsons Site into german. Why do you not all work on Alicsons Site? Now there is another (i guess useless attempt) to set up a Wiki which is called TextBook and hosted under textpattern.net. Sorry, this is just confusing and does not help centralising documentation.

alex

ps: in germany three Wikis failed already

Destry · 2004-12-27 14:28:07

Alexandra,

I think your real frustration here is that in your efforts to offer translation services, you are confused about what resources to actually translate. Very legitimate frustration indeed, if it is true. But whether or not that is the case, I do think you have a rather pessimistic view of TextBook, and are a little off target in your thinking that it’s “useless,” so let me give you some other angles to consider.

First, you indicate that you are a beginner. I’m a beginner too, relatively new to Textpattern, and I am not finding the existing “documentation” (a false label) to be very helpful, so rather than just gripe like most people do, I am trying to do something about it as well — not only for me, but for all new TxP users now and in the future, and that’s why I initiated the <a href=“http://textpattern.net/wiki/index.php?title=Main_Page”>TextBook</a> effort, a community effort to create a real TxP user manual that all other documentation efforts feed.

What is a real documentation effort?
Let’s make clear what a real “documentation effort” is in general, whether for Textpattern or anything else. A real documentation effort is one in which the finished documentation product (user manual) is immediately relevent to current product version, presents concepts in a logical manner, is concisely-written, is consistent in style and tone, is thoroughly tested, is religiously edited, is authoritative (meaning official), and is styled to reflect the product it’s discussing (i.e., has proper branding). In theory, if a tech product was shipped on a CD-ROM, this is the kind of documentation that would go with it. This real effort is the idea behind the TextBook initiative, and it’s the only real Textpattern documentation effort at all; at least as it’s clear from anything talked about in this community forum so far.

Comparing the current options…
The other resources you mention are not documentation efforts as suggested above. The Weblog stuff is simply that — ad hoc tutorials posted on personal Weblogs by anybody and about anything. Certainly they are noble in their cause and useful to many people, but they are NOT a real documentation effort, they are just small pieces of the puzzle that need to be collected, reworked, and integrated into a single, authoritative manual. Alicson’s Resources site, was a huge and badly needed step towards corraling all of the Weblog tutorials into a single window for easy finding, but that’s all it is so far, a portal that essentially maps to the previous Weblog stuff; there’s still no consistency in writing, there’s still no content editing, there’s still no logical concept flow that a real user manual would provide, etc; it’s just people’s various Weblog articles all roped into one place.

TextBook is not competing with the Resources site, it is a different animal. TextBook is solely focused on a comprehensive, authoritative, centralized user manual, whereas the Resources site is simply a directory of sorts for the ad hoc stuff already out there (including TxP template donations, plugins, etc.). In fact, it would be worth pointing out that TextBook is intended as a product in support of the Resources site, just as you suggest, because it will actually be a comprehensive source of information added to the Resources site collection. You can already see the placeholder for it in the Resources site, on the <a href=“http://textpattern.org/about/”>About</a> page, right under the Pending section (which is apparently a little outdated at the moment). You can surely expect the Resources site to be reorginized to better reflect it’s objectives, present its resources, and to accomodate other contributions like TextBook.

Why a wiki now…
TextBook is being developed in a wiki, and wikis have a tendency to fail; this is true. They fail because of two main reasons: lack of planning in their creation and poor control of their expansion. By their nature, wikis can spiral out of control very quickly, and when that happens, people generally abandon them, and the effort dies. I would say this is not the case with TextBook; so far it is shaping up very nicely, and unless someone intentionally disregards the basic user guidelines already established in the wiki, then the user manual should continue to develop in a clear, organized manner. If you had read this thread in more detail, you would also have noted that the wiki is not considered the permanent home of the TextBook manual; it’s only being used to assemble the major chapter sections. When <TextBook is more complete and content is reletively revised to a fine level, it will be relocated into a more suitable environment where simple edits/revisions and better presentation will be achievable (e.g. an actual TxP installation). That’s the idea, anyway.

Contributions…
If there is one thing that might slow the development of TextBook, it would be the community’s refusal to contribute to it, and though that might still turn out to be the case, it is way too soon to cast judgement in that respect. Grassroots documentation takes time to develop; nobody is getting paid to do it, so it’s expected that Textpattern users, community members, and/or Weblog authors will continue to write how-to articles for Textpattern on their own Weblogs, and by doing so they continue to support the Resources site. However, to make the information even more valuable (contributing in an even greater way), authors can offer their pieces of writing to the TextBook wiki, where the rest of the community can then test, integrate, and refine them so that they are indeed beneficial to a larger range of users. A real documentation effort is to take people’s initial authoring efforts and make the content better, and that’s what the TextBook wiki is for. It’s basic book writing/editing principles that have been practiced for thousands of years. Furthermore, authors get full credit for any contributions they make where content is already published on a Weblog somewhere, so there’s no lack of recognition in the effort. Right now, TextBook is basically a free service, a content editing platform, and it would be silly for authors to not to take advantage of it — contributing their written pieces to it for logical integration and editing — for the sake of the Textpattern user community.

Translations…
At the moment TextBook is an English version effort, first because that’s the default language for Textpattern, but more importantly so to focus content development, testing, and editing to a refined state. Once the English version is in a revised state, it will be targeted for translation into other languages. If I was translating anything, and I expect to contribute to French translations of TextBook eventually, I would want to translate something authoritative like TextBook, where it’s expected to be edited and reflective of the latest TxP version and functionality, not rough-shod and dated like Weblog articles often are.

I think it’s hard to see the value of TextBook right now because it’s still early, but with time and contributions, it’s real value will become apparent, especially to new users.

Destry · 2005-01-25 13:08:21

To anyone who might be coming to this thread for the first time (or not in a while), don’t pay anything but mild regard to the previous two posts; we are waaaaay past that now, as you might surmise by this much more recent thread, <a href=“http://forum.textpattern.com/viewtopic.php?id=5759”>%{color:gray}right here%</a>.

Now to the present, I offer this notion: With the recent take-off of the <a href=“http://txpmagazine.kbbu.de/all_sites/”>Textpattern Sites</a> collection, and with itâ

Last edited by Destry (2005-01-25 15:14:20)

Matt · 2005-01-25 13:37:32

As I’ve said before, I like Destry’s idea very much.

Since the purpose is to demonstrate some “best practices,” rather than just cool features or nice design, I think that site designers ought to nominate themselves based on whether they feel their sites can serve as clear examples for new users. After all, the rest of us have no way of knowing how simple or complex a site might be under the hood.

Here are the conditions that would make a site serve the purposes of this tutorial:

No mods to Txp code
No unused forms or pages
Predictable, familiar, and easily classified format (meaning if the site is a weblog, it has all of the expected features, like comments, an “About” page, and archive page, a list of links on the side, etc…)

This should be a way to get new users past the initial hurdles that so many face, like “how do I make an archive page,” or “how do I show content on a single article page but not on the list of articles.”

Destry · 2005-01-26 12:30:47

Good suggestion, Matt, and I like your ideas about conditions for a site, the nature of which fits in well with the whole point of the early TextBook chapters, which is to be relevent to the default package and targeted to new users.

May I ask a couple questions that might be on the minds of our listening audience…

First, can you expand a bit on the “no mods to TxP code” condition? Do you mean no hacks, no plugins, etc? I’m afraid most sites will be so modified, especially by knowledgeable designers, that no one will step forward because of this condition alone. Maybe we need a few more parameters to clarify this a bit.

Also, clarification on “no unused forms or pages;” I think it’s as simple as it suggests, but just want to make sure. Basically, hide/delete the stuff you’re not using? (This would make sense; you would want the supporting screenshots of backend to be clean. Good foresight.)

The last condition is crystal-clear to me, and should be to our listening audience as well. Furthermore, it’s critical for a usable model write-up. Excellent point!

Last edited by Destry (2005-01-26 12:35:04)

Matt · 2005-01-26 13:31:13

“First, can you expand a bit on the ‘no mods to TxP code’ condition? “

I mean no hacks to the default code. Basically, I envision a system in which a new user could download a SQL file containing the entire database for a tutorial site (with or without articles), feed it into his or her own database, and reproduce the example. Since plugins are stored in the database, plugins are no problem in this regard

You’re right to point out that some of the best sites have been put together by people who aren’t afraid to hack at their txp code, but hopefully the community can come up with a few nice, unmodded examples.

Yes — when I say “no unused forms or pages,” I mean what you think I mean. Delete from the backend any form that’s not used on a page, and any pages that aren’t used in a section.

Here are the first few examples I’d suggest:

The basic weblog: No plugins or css background images. Just the default install plus an archive section, an about section, and a custom search results section.

The intermediate weblog: Demonstrates a few of the “must-have” plugins like ob1_title, zem_article_image, rss_suparchive, perhaps even the mdp_automatic thumbnails hack, etc…

The portfolio: Instead of picking just one way of the many many good options for this, how about one site with several different sections, all displaying the same set of images with different gallery plugins? A section for imagepattern, one for jmr_gallery, etc. Here’s a compiled list of image gallery plugins

The corporate site: an example of mostly static pages, perhaps for a fictional company, with sections such as: products, clients, news, and contact.

There are obviously more advanced applications of Txp than anything I’ve listed above, but by the time someone’s up to a really challenging site, he or she is probably past needing tutorials like this.

Thanks again, Destry, for your efforts.

Last edited by Matt (2005-01-26 13:32:04)

Destry · 2005-01-26 14:58:43

Wow…this is evolving quick! Excellent.

My vision all along has simply been with producing a manual (as in written text) about how to do things. What you are suggesting is paralleling that with actual working demos, as written about. This is cool.

I will continue forth with my initial objective, which is simply getting TextBook written (a community effort, by the way), and steer chapter 3 along the lines of what you are suggesting to do with actual, shall we say “hands-on learning installations.” If someone else wants to create the learning installations in parallel with the writing, that would be fantastic. In a sense, one would be the documentation for the other. Then we could simply link to the installations directly from the relevent TextBook sections.

Your good examples also make me think that it’s not necessary to use someone’s existing designs as they are (which was my original thinking, and why you would need a site owner to be involved to begin with), but now hearing your thoughts (especially the “fictional” idea) it seems to me that these could all be done from scratch; all we need to do (as you’ve nearly done already), is pick which features to discuss, and then build a working model with those selected pieces; a wonderfully simple approach. Well done Matt.

If you don’t mind, I’ll use your suggestions exactly for the approach of the write-ups. So what we really need to think about then is what features to include in each model. I’d say you covered the basic Weblog model just fine. That would leave just selecting exactly the features (functions, plugins, whatever) we want to create in the other three. Specific ideas, anybody?

EDIT: If the manual keeps going in an interactive direction like this, we may just have to include a <a href=“http://forum.textpattern.com/viewtopic.php?id=5937”>tag and plugin selector</a> for the relevent appendices too.

Last edited by Destry (2005-01-26 15:10:35)

Destry · 2005-01-27 16:22:11

Well, the TextBook wiki just got attacked. Someone actually signed in and completed wiped the home page clean, replacing it with some spam links to prescription shit.

Only an administrator can roll back the wiki to a previous state, and as far as I know, that’s Remillard and Dean.

Being that Dean has better things to do, and being that Remillard has been a bit scarce these days, maybe we need to consider some other backup measures. Obviously another admin or two would be appropriate, but perhaps further we need to think about the platform itself.

Maybe we need to port this effort sooner than later to a TxP install and think about how authoring contributions will be handled that way. The nice thing about this idea is we could also use Textile and style it up nice and petty.

UPDATE: Both Dean and Remillard have been notified. Haven’t heard from Remillard, who is really the admin for the wiki, but Dean is trying to look into the problem.

Moderators: Any chance of retitling this thread to “TextBook: The Textpattern User Manual” or something with TextBook in the label? It’s matured enough to probably need it.

UPDATE2: TextBook is restored. But I still would open things up for discussion about what we should do in the future, because this could happen again (I suppose) and try the patience of the gracious.

Last edited by Destry (2005-01-27 16:33:02)

Destry · 2005-02-11 09:59:47

zambaroo…done.

cboone · 2005-02-12 19:44:00

I’d like to be able to write for / edit the wiki. Can someone please hook me up?

Thanks…

Destry · 2005-02-14 15:50:01

cboone….done. Sent info via your forum account (behavior was a bit odd, though, so if you didn’t get it, let me know).

Textpattern CMS

Textpattern CMS support forum

#49 2004-12-26 20:03:21

Re: [wiki] User Manual

#50 2004-12-27 14:28:07

Re: [wiki] User Manual

#51 2005-01-25 13:08:21

Re: [wiki] User Manual

#52 2005-01-25 13:37:32

Re: [wiki] User Manual

#53 2005-01-26 12:30:47

Re: [wiki] User Manual

#54 2005-01-26 13:31:13

Re: [wiki] User Manual

#55 2005-01-26 14:58:43

Re: [wiki] User Manual

#56 2005-01-27 16:22:11

Re: [wiki] User Manual

#57 2005-02-11 09:59:47

Re: [wiki] User Manual

#58 2005-02-12 19:44:00

Re: [wiki] User Manual

#59 2005-02-14 15:50:01

Re: [wiki] User Manual

Board footer