You are not logged in.
This was a post I was making to reply to some of the ideas being brought to light about TextBook in this thread, but my response was getting out of context and nevertheless needs more attention as a top thread; and low-and-behold, it seems rather timely too considering billdale’s recent post here, which I tend to <strike>agree</strike> somewhat agree with.
Again, quotes are from here:
maniqui: I think “Documentation” already exists: it is the TextBook.
That concise sentence is my stance exactly.
We don’t need yet another place to look for documentation in general. Distributed information does not make it easier for a new user to learn; nor does wild-hyperlink-goose chases to find the gold egg, which is what you put users through when you create more places for them to look. Searching distributed information takes time, is tiring, and wholly unnecessary. If the overall documentation effort for Textpattern is ever going to move forward properly, focus needs to be given in one place, and one place only. From day one that has been the objective for TextBook, and why a wiki platform was selected, which is far more appropriate than a bulletin board system. Bulletin board systems are for quick thoughts, bad spelling, and biased opinions; therefore they are inherently BAD for serving as the final documentation resting ground.
Under this same reasoning, I don’t understand why the Tips/Tricks/Tutorials section of the Resources site, and now the new FAQs site, should be separate efforts from TextBook. All of the information in those two locations could just as easily have been developed in TextBook thereby consolidating the documentation effort and making it available in one place (one site link to follow); even more, it would have opened-up those pieces of information to other writers to ensure information is revised and corrected over time. As it is now, you have to take what you get from the person who originally wrote the piece, and frankly, a lot of what’s in those places could certainly be improved for the benefit of a new user.
It would be monumental and good for everyone if the stakeholders got together and combined these resources. TextBook can just as easily have a branch for an FAQ, and and branch for Tips/Tricks/Tutorials, those entities don’t have to be lost, we simply put them all together under one umbrella where they belong, working together and not in competition, and where more “authors” have access to the content to make it better — that’s the real key here, more hands-on!
However, as people have pointed out below, there are seeming problems with TextBook right now. The statement below are powerful statements, good statements, they begin to probe the problem that truly does exist. Why does TextBook only have 88 users out of potentially hundreds? And why out of those 88 people is it only that a handful every really do anything, especially when you see the names in there and know these people know Textpattern well enough to contribute something of substance?
zem wrote: I suspect more documentation would get written if it was easier for people to contribute small pieces, rather than feeling that they have to write an entire chapter.
zem wrote: I think the main problem TextBook has is that there are too many barriers to posting: you need to ask for an account, and it doesn’t seem receptive to small contributions.
For the record, “small pieces” of contribution — whether it’s an FAQ or simply correcting another person’s spelling — have been encouraged in TextBook since the beginning (yes, ubernostrum, your contribution counts), but perhaps we need to find ways of making that more clear. Well, I’ve given you one good idea, a solid idea, we create two branches in the wiki: one for FAQs and one for Tips/Ticks/Tutorials and then all the “small pieces” people can have at it in unrestricted fashion.
Another idea would be to start adding page placeholders in the wiki Table of Contents where people want to see something written about. These placeholders would be indicated as red links, meaning they need written, thereby making it easier for potential contributers to, well, contribute in small pieces.
As for the login process, this is something I’ve also been considering as a barrier to the wiki so I’m glad it was pointed out. The login process was started because of the spam attacks that the wiki was starting to see. Some of you may remember when the entire TextBook index was wiped clean and replaced with a single link to somebodies personal site, or whatever it was. As far as I can see, this is what we face on a regular basis if we simply have an open wiki to the world. Yes, there is rollback, but who wants to spend all their time continually rollbacking the wiki when it can simply be avoided with an free account process. I can tell you right now I don’t want to be the one who has to rollback the wiki 5, 10, 20… times per week. It works for sites like wikipedia because that site has millions of users who watch it like a hawk at every second. That’s not the case here. Maybe I’m not seeing all the possibilities, so I’m certainly open to suggestions.
Here is one idea, and it would rely on a number of volunteers to serve as on-call wiki rollbackers (but it would not include me). Ideally we would have several who represented all hours of the day (international time). These people would be given admin accounts in the wiki, with the understanding that their sole purpose for the time being is to rollback the wiki when a spam attack occurs. Then when an attack does occur, the call is put out to the wiki-rollbackers. We’ll make the rollbackers known in the TextBook Notes thread so it’s always available who they are.
mary wrote: We already have the problem of people joining but not contributing to the wiki, and I guess its because the wiki scares them or something.
Yes, this is a puzzler, people join and then don’t do anything significant, but I think this is par for the course with anything. Look at the Textpattern forum’s user list for example. One of the things I’ve always thought would be interesting to do is a pie chart diagram of the number of posts of the users in here who have accounts and what their post counts are (grouped in percentage ranges). I think you would see that out of the thousands? of users there are, most have zero posts.
zem wrote: when a thread contains enough information to be useful, someone can copy it over to Textbook. I’m sure Mary would be more than happy to create Wiki accounts for anyone willing to contribute.
I’m not surprised you are not aware of the current user accounts protocols, zem, considering you have never asked for an account yourself. EDIT: But that’s fine, don’t get me wrong, I don’t expect you (or Sencer and Kusor for that matter) to write documentation, I think your time is better served on the developing, though any writing you want to do is greatly appreciated. The FAQs is great and useful, but I don’t see why those ideas are not written in TextBook, where they can then be maintained by others so that you developers can get back to programming more. If TextBook is hard to approach, then lets figure out how to make it more approachable.
Let’s consider this thread an open round-table for bitching and offering good suggestions about making TextBook better. No holds barred.
Last edited by Destry (2005-10-28 13:49:12)
OK, here’s the first things that popped into my head:
Regarding merging of everything into one place: I can see the rationale, but I think the TXP Resources site ought to remain separate. A lot of this is my inner Unix geek coming out and chanting “do one thing, and do it well”; in the case of the Textbook, the one thing it does well should be providing a relatively static user’s manual for Textpattern, with complete documentation of all the tags and features and a solid introduction to how TXP works. That’s something that a properly-administered wiki is pretty good for.
But plugins, hacks and other “tips and tricks” fall mostly outside that. I’d even argue that the Textbook section on setting up different types of sites is close to being outside the scope of a “user manual”-type reference. That sort of information is also better presented through a CMS like Textpattern, particularly because it allows active discussion to go on in the comments for each article. And I know the wiki has discussion pages, but those can be incredibly hard to follow even for people who are used to the format. I often get lost in Wikipedia talk pages while trying to figure who said what in reply to whom and when — following discussion, and participating usefully in discussion, is far easier in a TXP-style comment thread.
Also, there’s the matter of the huge amount of data that would have to be migrated if the TXP Resources site were to merge into TextBook, but that’s another consideration entirely.
As for wiki accounts, I’m not sure that throwing the doors open to anonymous editing or open registration is what’s needed; it’s easy enough to get an account, the problem, as everyone is aware, is that a number of us (myself included) don’t actually spend much time contributing. I’m still thinking this one over and trying to see what the best solution would be.
If you do decide to go that route, though, and need someone on the east coast of the US to keep an eye on the wiki during certain hours of the day, I’ll happily volunteer.
You cooin’ with my bird?
Thanks uber, good thoughts. For clarification, I wasn’t suggesting merging the entire Resources site into TextBook, only the section or two that really dealt with documentation. Same principle as what Stuart brought up about templates, they should really go in TextGarden (but that’s another issue I think is recognized)
EVERYONE: Let me be clear. I fully support the Resources Site and all efforts there are applauded loud and long, I’m not suggesting it be folded under, hardly! I’m simply talking about the little documentation bits that are there.
EDIT: I think it’s too easy for Joe/Jane Blow to slap something down in their Weblog and then add it to the Resources Index. Thats what we relied on in the beginning, it’s not what we should keep relying on. One of my gripes when I was new to Textpattern was simply trying to understand the documentation that was written; half the time it either assumed you were a developer or it was simply just vague, leaving out critical details, not to mention basic writing skills and content organization. This just goes back to the point I’ve been making all along, the information is still out of the hands of other authors who might otherwise help make the information better and keep it up to date. Put that information into the wiki where more hands can make it better.
But I’m repeating myself now.
OK, great, please continue.
Last edited by Destry (2005-10-28 13:59:05)
I signed up for a wiki account. I added a section once. I haven’t since. Here’s why.
I’m not familiar with Wiki markup or the wiki that was used to make the site. I didn’t feel like learning a whole new application just for the sake of that one site. I use Textpattern. I learned Textile because thats what Textpattern used. It took me about 5 minutes to learn all I’ve need to know about Textile. It took me over 1 hour to post a 2 paragraph entry on the wiki.
So if you’re wondering why people don’t contribute more to the Textbook, in my case (and I know that of at least a few other), the reason is that its harder than it should be. If the Textbook were built with Textpattern, I know that I would be more inclined to add information to it. Now maybe thats not possible and everyone but me feels that a wiki is suited better for this purpose but I thought I’d mention that. Textpattern Resources runs Textpattern using the self register plugin so anyone who signs up can contribute, just as with the wiki.
As far as the wiki goes, I find it hard to use and find information. Take a look at the Wordpress Codex. The front page is clean, simple and neatly organized. The Textbook is a long listing of topics, a majority of which are marked In Progress, Needed, are inactive or lead to blank pages. I would imagine that first time visitors get the impression that there’s not much there. As far as navigation goes, maybe the left side navigation could be beefed up to make it easier to browse through the wiki and the main page could be reorganized to highlight more of the information thats in the wiki.
Some people also prefer to post tutorials or tips on their own site. If thats the case, why not just link from the wiki to other peoples site. The goal should be to help people find information, not to accumulate as much as possible in one place. You can search the internet and find tons of poorly written tutorials and explanations on everything under the sun. I don’t think Textpattern documentation will be any different. Some write ups will be better than others. There’s no way around that. The key should be to make it as easy as possible for people to contribute and find information regardless of the software being used or the URL where you can find it.
If all else fails, just give away an iPod or something. That seems to work for everyone else.
I take some blame for not having contributed, especially as I was more involved at the beginning.
Some of the diagnoses here are correct, though. I logged in to TextBook once or twice, but I didn’t get good vibes out of wiki – it’s not that it was TOO hard to use, just that it was annoying and nothing was immediately obvious or worked like I expected. I don’t relish learning wiki markup, which I have never used or needed before and will probably never need again.
Then, too, I feel that my sometime niche (semantics) needed some rethinking, and I haven’t found the energy to get it done. When textpattern first exploded I had an early a-ha moment, did a brain dump and created the semantics article and it has proved helpful. Now everyone’s input has made me think maybe that’s out of date now and needs to be rethunk before going into textbook.
In short, Destry, maybe I’m just as bad about contributing as you are in getting your photos organized online :)
wilshire makes a valid point about Wordpress Codex, but I don’t think any of the problems mentionned above have anyhting to do with how the Home Page is set up. Nor does it have anything to do with MediaWiki being used…
Of course this can be discussed but I think first and foremost we should underline <strong><span style=“color: #006600”>The Great Job Destry has done with TextBook</span></strong>. Before he launched this documentation effort, only Joel Dueck’s manual was of any help to anyone starting with textpattern. That is, aside from the forums.
And there comes my analysis of the “problem” : though there might be a lot of zero post account , the community has a strong dynamic and the forums are among the most responsive and helpful I have ever seen built around a CMS. What deterred some away from Textpattern was the fact that it did require some learning and digging, but it never bothered those who prized the powerful flexibility of this tool. Some more “in the box” tool may have attracted more traditionnal thinkers and documentation effort seem to have been way easier for other communities.
I might be wrong, but I think the very thing that makes this community an incredible place is the human somewhat fuzzy, “out of the box” and destructured mode of learning. Ideas are flowing, things are tested… somewhat of a workshop I don’t know how to sum it up and in french I would say we do a lot of bricolage in the noble sense of the term.
As Destry said, the Wiki relies on the most proficient users and on their contribution. But most of the time we devote to the community is here, where the life of the community is. TextBook might need to open contributions, and as Destry said if necessary depend on rollbackers to fight the spam attacks (I am willing to contribute in this area).
I think TextBook is the way to go, a central place is key to a real documentation effort, we can not depend on link to personnal blogs : content should be integrated into a common effort. Consistency and continuity is of the essence here
Last edited by davidm (2005-10-28 23:10:53)
.: Retired :.
I’m with Wilshire almost 100 %.
Me no likey Wiki. It seems somehow logical and appropriate for Textbook to be written in TXP. It seems the kind of puzzle perfect for this community. Show how to use TXP using the tool itself. Is this too much recursive or meta thinking? If we can use TXP to “write a book” doesn’t that really demonstrate its use as a publishing system?
I’ve been playing with an idea like this to show what CSS is and how it works in TXP. I don’t have the concepts completely worked out but what’s there now shows me struggling with the section/category issue and working with plugins and tags.
I have to be honest and say tho, that the forums are really where I find what I need and (like to read). The forums are a goldmine that somehow, someway could/should be culled and indexed. The code is all in here.
So I’m with DavidM on this: “I think the very thing that makes this community an incredible place is the human somewhat fuzzy, “out of the box” and destructured mode of learning. Ideas are flowing, things are tested… somewhat of a workshop I don’t know how to sum it up and in french I would say we do a lot of bricolage in the noble sense of the term.” TXP requires a dedication to it before its secrets are revealed. I think maybe it should stay that way. No offense at all, Destry, I know the manual is needed and neccessary but the TEXTBOOK feels to me like an anatomy primer, missing the heart and soul of TXP. I can contribute fuzzy poetic documentation but I know that’s not what you want.
This is still the smartest, best spot I’ve found in over a decade of wandering the open source realm. Thank you all for being here and doing what you do.
Last edited by neutrino (2005-10-28 19:39:15)
Great feedback, everyone, keep it coming.
The thoughts about the wiki code and the general vibe of the environment is well taken, and I really want to change that. I had always envisioned the wiki as the “drafting” ground for the documents that would eventually go into a TxP install. I still would like to see that. Maybe I had it backwards, maybe TextBook articles should start getting ported to the FAQs, which is a TxP install. Though I don’t think the title FAQs would be appropriate at that point. In any case, I do like the idea of the book being in a TxP install, eventually.
In the meantime, we have the wiki, and it does have a lot of advantages, like for example it is now international, which you can’t do with one install of TxP. Nevertheless, it clearly needs some improvement. I’m going to make a list of all the good points of contention that are brought up in this thread, and I’m going to do whatever I can to improve TextBook in those areas. So please keep the honest and excellent feedback coming.
One thing I will get to ASAP is update the wiki to a new version; that will enable us to improve the side navigation a lot, at the sametime give it a fresh look. We’ll also look at the WordPress codex structure and see how that might help shape things too.
Ubernostrum mentioned something that has been nagging me too, the section about building different types of TxP sites. I think that chapter is just too ambitious and looks bad sitting there all empty all the time. This is where I think the FAQ type approach shines; so another thing to be looking at in all of this is the format of TextBook.
As far as the wiki code goes, yeah, it’s bizarre, but maybe we can have a text file staging area, where those who don’t want to bother with the wiki itself can still write something, stick it in a “pickup” box, of sorts, and then wiki-ites can convert the text to a wiki content. I’d be willing to do that.
Anyway, just getting these ideas out quick. I’ll get more organized.
Also, let’s not forget to point out what is good about the wiki too, so we don’t accidently change what does happen to work.
jdueck: Touche, bra, touche! ;)
davidm: You do as much as I, and a lot more considering all the other areas you get involved with. Salute to yourself as well.
I disagree. A wiki is the right tool for the job. How would you let everyone participate without it ? Assign articles on specific subject, then assign people to proof-read it, then other people to validate and publish it ?
Ok, as long as you put some hard dollars on the table to pay these peoples. Not to mention TXP is not nearly mature enough in those areas to get the job done. If not, writing documentation, correcting errors, adding things, should be as easy and plain as possible. And “possible” is very large in this day and age.
Now, that said, I agree the MediaWiki markup is not Textile. First, it’s still archaic on several ways (I was trying to use it on another project, with non geek, and needed to handle tables. Oh my f… god it’s horrible). Second, it’s a different markup language than the one we use.
So yes, maybe MediaWiki is not the right tool for the job (and believe me, I would be the first one to praise a TextWiki software around here). But a wiki is.
Last edited by Jeremie (2005-10-28 20:34:36)
Moving to a different wiki product is certainly possible, but I don’t see where it would be worth it unless it really solved the “wiki syntax” issue that is being brought up. Also, I would not know about the porting issues that might arise, and being that we have all the translation work going…changing products now might be creating more headaches than solving any. I’m inclined to think it’s a step too far; maybe better to just upgrade and improve what we can with what we have running.
Mediawiki code is awkward if you try and write it by hand, but if you use the built in code buttons, it’s simplifies things considerably. Granted the buttons are limited. Also, you can use regular HTML too, no reason you have to use wiki formatting. In any case, the idea is to just get the words down, somebody else with wiki syntax kowledge will come along and clean it up. Baseline: wiki syntax should not be the sole reason for not sticking something into TextBook.