[wiki] TextBook Issues (let's bring it together already)

Jeremie · 2005-10-28 23:46:37

zem wrote:
FWIW: the PHP manual is one of the best online manuals around, and it’s structured more like a CMS than a wiki.

I do believe it has tools and features that TXP don’t have for that job. For example, I can’t imagine this manual has been written without attached discussions tools (aka forums) per page topic and so on, revisioning, versionning, smart notifications to people in charge, and so on.

davidm · 2005-10-28 23:54:47

I understand the “devil’s advocate” stance. In a way, I agree with the Keep It Simple and Stupid philosophy : the important thing is for it to work. Yet I think in time, when the doc is big and evolving, we’ll see the advantage of going the wiki way…

zem · 2005-10-29 00:10:41

I guess what I’m suggesting is: go with the flow, let the behaviour dictate the tools, rather than trying to change behaviour by using different tools.

Jeremie · 2005-10-29 00:16:38

Destry wrote:
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?

I’m one of these people (having some TXP knowledge from some time now, some forum presence, and making very sparses to nothing as TxtBook contributions are concerned) so I’ll try to respond. Not in a defensively way, I will just try to search why is that so (frankly I don’t really know myself), so that when other people do we might see a pattern, and ten fix it.

First, there is a language barrier. My english can be far from perfect (I don’t believe you guys let me use the “outputed” word on these forums for month without telling me… I’m ashamed :p), and is more difficult/less pleasant to use when writing. Especially when we try to taught someone something, where form are as important as substance to truly explain something.

On the other hand, I don’t rememebr doing anything for the french translation. Mostly because it’s a translation I think, a mimic of the english one. I do think a translation is important in theory, but for myself it’s not a priority right now. In a strange way, I was thinking that I could help more people with english content ‘forum or otherwise) than on a french translation of the manual.

Second, I acknowledge now I do have some issues with the WikiMedia markup. Not the syntax itself (I’m a geek enough to use it), more because manual pages are mostly very strictly formated (I’m talking about the tag page, which are by far and in my opinion the more important ones) as they should, but this format make it a little harder to write from scratch. It’s not that big a deal (it’s very minor), but it’s on minor thing, and another one, and another one.

Another issue I have, though more narrow and specific, are the new tags or tag related feature. I mostly don’t understand what the dev team are doing, because the subversion comments aren’t really helpful on that subject – to me.

Another issue, is the strict formating of the wiki at whole. For example I wanted to publish the hdiff patch to make the Textile class french compliant, I don’t even know where to put it. And creating a new page from scratch for MediaWiki is a bitch…

Also, for some time I wasn’t sure TXP was the right product. It had some major things lacking (or wrongly done), and I was still investigating other product for the job of my “default cms tool”. This is no longer the case however (it still has some issues, but I will bitch about those some other thread :p).

For a conclusion, I would say that – for me – it’s by far mostly a problem of getting kick in the butt (well, not kicked in fact). I can do more, I do think I should do more, and I should. Well, I will try anyway :p

One little thing that would help me, is from time to time some call on specific subject. Like “we got a Using SVN to install and update TXP page that is no good, we need some help on it” and so on. Give a purpose or a direction, that sort of things. And another one little thing, would be a XML feed of the “recent changes” page. Something I could subscribe to, and reming me Textbook exist and I need to read more of it – and so, have more chance of seeing errors and so fixing it, and so on.

Edit: about the appearance of the “strict formating of the wiki as a whole”, there’s a page that says:

This page describes many precedures and methods for authoring and editing collaboration in TextBook. The methods are particularly important as more and more people try and work together, and as new revisions (and versions) of Textpattern are released. Please review this entire page before doing anything in TextBook.

This page is 7337 bytes long ! And others pages are heavily pushed for reading too. So yes, I can understand some are really scared about conributing in any ways. I don’t support a chaotic wiki, and I do have an OC mind and like the right things in the right box, but that’s a lot of informations to read, understand, remember for the casual contributor.

Last edited by Jeremie (2005-10-29 00:51:51)

Jeremie · 2005-10-29 00:19:05

zem wrote:
I guess what I’m suggesting is: go with the flow, let the behaviour dictate the tools, rather than trying to change behaviour by using different tools.

I agree. But (but ?) for me, the flow is using a wiki. More important, it is what we have. Switching tool need some really good cause to do it, because it consume tim ethat could be used to develop, write doc, debug, and so on.

Mary · 2005-10-29 02:06:08

I’ve always felt that wikis were great tools, and yes, we need to have some basic structure. That said, the formal tone is off-putting, I’ve always felt that. Can we not tone down the officialness, rather than making it the official documentation?

Then the core devs can decide on a person or persons to use the wiki info as a guide to create the official documentation. Official documentation never has “real life” examples, it just shows you how everything works. That could be Txp-powered. Then there’s also less pressure on the contributors.

The resources tips/tutorials should probably be merged in one way: it should be a pointer to resources, not containing them. i.e: someone blogs a tutorial the resources site could point to it. If someone wants to compose it elsewhere, the wiki makes more sense.

I really like Instiki too, its simple, easy to use and far less overwhelming.

Jeremie · 2005-10-29 02:56:50

mary wrote:
Can we not tone down the officialness

Worth a shot I think.

rather than making it the official documentation?

I disagree on this one. TXP need a official documentation. And Destry (with the wiki active contributors) is the only one doing it, all alone, all by himself.

I mean, if Textbook is not the official documentation (well, the only one in fact), who will setup, create and maintain one ?

Then the core devs can decide on a person or persons to use the wiki info as a guide to create the official documentation.

Devil’s advocate: why haven’t they ? TXP is what.. 2 years old ?

Official documentation never has “real life” examples, it just shows you how everything works. That could be Txp-powered. Then there’s also less pressure on the contributors.

PHP and MySQL ones have. They are mostly user’s comment, but it’s still in the official documentation.

I really like Instiki too, its simple, easy to use and far less overwhelming.

Well it’s ruby… but it seems nice yes. If Destry agrees, maybe you could write an import script from MediaWiki to test it in the open ?

ubernostrum · 2005-10-29 10:23:11

I’m all for using whatever technology is most effective at letting people easily contribute useful, organized documentation, be it MediaWiki, Instiki, TXP or something else. But…

Our root problem here is not one of technology. It’s been said already, but it bears repeating: technical writing is hard. And it requires talents and techniques very different from the talents and techniques that make people good programmers or web designers. What’s most needed is a group, not necessarily very large, of people who can write effectively, and who have the time and motivation to write good documentation for Textpattern. For some areas, there’s already fairly good developer-oriented documentation which could be used as a starting point, which reduces the amount that needs to be done “from scratch”.

Secondary to this is the problem of organization. Currently, the wiki could stand a lot of improving in that area, especially as pertains to meeting the needs of different types of users. When I’m doing IA work, I usually try to think in terms of questions — when this type of user comes to the site, what are they looking for? — and I think that’s as good an approach as any to producing useful documentation for Textpattern. As I see it, there are three main groups of people who need TXP docs:

“Average users” (oh, how I hate that phrase) who don’t have much technical knowledge, if any, and just want to set up a website, usually a blog, and have it work. Their primary questions are going to be things like “Where do I get TXP and what version should I get?”, “How do I install it?”, “How do I post new entries”, and “How do I get a nicer-looking theme?”
Web designers who have knowledge of HTML and CSS, but maybe not PHP, and want to use TXP to set up a client’s site. Their primary questions are going to be things like “How do I organize the site’s content?”, “How do I customize the page elements and display?” and “How do I use plugins?”
Advanced developers with solid knowledge of PHP who want to really customize TXP, whether by hacking on it or by writing plugins. Their primary questions are going to be things like “How is TXP’s code base organized?” and “What global variables and functions dos TXP provide that I can use?”

I think the wiki would do well to align itself around these sorts of models, probably fairly explicitly — that is to say, going to the main page of the wiki would present a short blurb about Textpattern, then break down into sections “For new users”, “For web designers” and “For developers”, each of which has its own little table of contents linking to appropriate areas. Finally, one more section of the wiki would be a comprehensive listing of TXP’s features, built-in tags, built-in global variables, and built-in functions.

That would be a lot friendlier, and would let various types of interested people come to the wiki and immediately find documentation that’s useful to their purposes.

Destry · 2005-10-29 10:38:54

zem wrote: I guess what I’m suggesting is: go with the flow, let the behaviour dictate the tools, rather than trying to change behaviour by using different tools.

Although that sounds good, it’s not very elucidating; but what I think you mean to say is since there’s only a handful of people writing in the wiki anyway, use a CMS and add a few more authors/editors to it (besides just zem, Sencer, and kusor), and call it established. Something like that?

Looking at the wiki side: if Textile is in Instiki, that would certainly address the issues of syntax, but what about the language efforts? It would not be fair nor right to yank that rug from under those who have volunteered to translate information already. I think the internationalization aspect of TxP is important, as this community proves. David didnt’ mention if Instiki handles the language aspect too, but I’m guessing it does or he would not have suggested it. If so, then I’m not against the idea of moving to Instiki, that would be the first place to start, and in the process we would look at possible ways of reshaping the presentation of TextBook, since that also seems to be a common focus.

Jeremy’s points about the “official” tone of the wiki’s auxiliary information is well-taken and I think it echos those points put forth earlier about the wiki not having a good “vibe”. I don’t think we will be able to make every single person happy here; there needs to be rules, especially in a wiki where people collaborate, you need to ensure consistency, or the whole thing turns into a big fucking can of worms real quick. Wikipedia has pages and pages of rules and quidelines, and they exist for a reason. On the other hand, we certainly can rewrite auxiliary information to take the “official” tone out of it, I’ve tried doing that a bit over time, but we can keep working on that, certainly.

Perhaps while all this is being worked out, the time has come for wiki leadership to be leveraged a bit; I’m happy to share the ugly role of decision maker with another person or two. In the beginning there was Remillard (still is theoretically), but he has been silent now for a very long time and I think his actions speak for themselves. So, consider this an open invitation to whomever wants it to share the wand of wiki power. We will let Dean know of course (the other Admin), but I don’t think their will be a problem there.

Basically you would have access to the backend and help do things like shape the wikis future structure, make rules, upgrade the wiki system more timely, etc. I would prefer to have someone who is not opposed to wikis and comfortable working in the backend, and also someone who has been visible as taking a real interest in the wiki project over time. Looking back through TextBook’s history, the person who has consistantly and ardently been outspoken about the wiki is davidm, and I would first offer the role to him. Additionally, I think it would perhaps be a good idea to have a third person too, someone who perhaps represented a devils-advocate stance in things, and in that respect their are a likely good number of people, but again someone who comes to mind is mary, and I would first offer her a shared leader role as well. I can’t begin to assume that these people even want the role considering everything else they are doing already (believe me, I know, this community is only a fraction of my time) but if you do, then we’re all happy to have you onboard, I’m sure.

Oh, I wanted to add one thing about styling wikimedia, the CSS for wikimedia is very complicated. If Instiki has even a remotely less complicated CSS process, then that would be a huge plus and make it a lot easier to consider alternate presentational formats for TextBook.

Destry · 2005-10-29 10:44:45

Yes, uber is right on the money in many respects. Writing is not easy. Having a masters in Technical Communication myself, I know how complicated it can be, all the user-centered principles and considerations that come into play (there’s many), not to mention just plain-old good writing skills, and the theory behind it — which is why I chose a direction in new media as opposed to print (though the principles are largely the same) ;)

I like the ideas for reorganizing TextBook, the current layout was really just to get the ball rolling, it’s expected to change as need dictates and voices are heard.

davidm wrote: One thing would help building a community of doc writers : add a forum here dedicated to contributors of the wiki. I know this might seem redundant and yet one other forum to clutter the community but I truly think discussion page on the wiki lack the appeal of a forum to structure debate on documentation writing.

I think this is a great idea too, and one has to wonder why it wasn’t done a long time ago; but rather than just focus on the wiki, it should allow focus on all the doc resources available, with perhaps a sticky for each one where specific details can be maintained (for example: simply move the TextBook Notes thread and the FAQs threads and you’re practically half-way there). Also, there’s a lot of doc-specific threads floating around the TxP Forum, those could be lassoed into this specific forum for improved centralization of like information. Finally, it probably wouldn’t hurt to stick the new forum in the #2 spot, right under the “Announcements” forum, but don’t just call it “Documentation” that’s way too generic and vague, and will likely give people the wrong impression. I see it as a thinking ground for improving the real documentation resources so it needs a title that captures that objective — like “Doc Resources and Planning”. That will certainly get people’s attention, while at the same time suggest that it’s the starting point, not the end-all.

Last edited by Destry (2005-10-30 11:36:00)

Mary · 2005-10-29 12:20:05

Uh, what is it I’m the devils advocate for? I’m likely misunderstood. ?

Destry · 2005-10-29 12:42:02

Heh…sorry, all I meant was that you might be a good voice of balance. You and a few others commented about the “official” tone of the wiki, so I’m thinking having an admin with perhaps alternate viewpoints about that would do well to represent that portion of the audience; i.e., help ensure things are written less offcially, I guess (as well as do other admin-like things).

The self-proclaimed “devils-advocate” is really zem…

zem wrote: Again, the devil’s advocate asks…

We always need one or a few of the devil’s advocates to ensure things are looked at from all angles.

Mary · 2005-10-29 12:50:29

Oh ok, I was like “What did I say…”

davidm · 2005-10-30 12:19:24

Destry wrote: (…) David didnt’ mention if Instiki handles the language aspect too, but I’m guessing it does or he would not have suggested it.

Well, no I did not check this : I will. The reason why I brought this up is the “crisis” that we seem to face and the fact people don’t like MediaWiki’s syntax and want a lighter tool. I do think we need a wiki not a CMS, thus the Instiki proposition.

(…) I don’t think we will be able to make every single person happy here; there needs to be rules, especially in a wiki where people collaborate, you need to ensure consistency, or the whole thing turns into a big fucking can of worms real quick.

We are on the same page here, I most definitely agree with you.

Perhaps while all this is being worked out, the time has come for wiki leadership to be leveraged a bit; I’m happy to share the ugly role of decision maker with another person or two. (…) Basically you would have access to the backend and help do things like shape the wikis future structure, make rules, upgrade the wiki system more timely, etc.

Well, if you want my opinion on this, the problem is not leadership nor more timely updates or rules or whatever. The problem is that we don’t have enough people writing. Forget the whole “technical writing” is hard bit : How come other communities manage to get things done ? Are they all technical writers then ? Of course not. Do you think Wordpress (or whatever CMS) contributors are better skilled than we are ? I do not. It’s not a matter of skills, but a matter of motivation.

Motivated people find solutions, not excuses. The thing we have to build upon is collective skill. I might not be able to write a whole clear and concise page, but I can write good bits and the more people contribute and edit, the better the doc will become. Everyone can bring something. You want my opinion : people who are currently learning txp will maybe write some parts about the basics better than I would. They just came to understand some things that are fairly obvious or ingrained in my head and thus harder for me to explain sometimes.

This is where we have to make it easier for people to contribute. As I said I am willing to be one of the rollbackers if the wiki is attacked but by controlling access we loose the collective-incremental-bit-by-bit-improvement-dynamics. Yeah we can improve the main page organisation (though it does look good to me already), but it’s not the point.

I would prefer to have someone who is not opposed to wikis and comfortable working in the backend, and also someone who has been visible as taking a real interest in the wiki project over time. Looking back through TextBook’s history, the person who has consistantly and ardently been outspoken about the wiki is davidm, and I would first offer the role to him. Additionally, I think it would perhaps be a good idea to have a third person too, someone who perhaps represented a devils-advocate stance in things, and in that respect their are a likely good number of people, but again someone who comes to mind is mary, and I would first offer her a shared leader role as well. I can’t begin to assume that these people even want the role considering everything else they are doing already (believe me, I know, this community is only a fraction of my time) but if you do, then we’re all happy to have you onboard, I’m sure.

Okay… I appreciate the offer, but with the fast building of the french community, I think I would better focus on french support and doc translation, and if I can a bit of doc writing as I have done so far. Rollbacking I am willing to take, but to me the problem is not adding heads to the leadership : I don’t think I am wrong thinking people know you are legitimate and dedicated as TextBook leader (if they don’t, they should their head examined ;p)

Oh, I wanted to add one thing about styling wikimedia, the CSS for wikimedia is very complicated. If Instiki has even a remotely less complicated CSS process, then that would be a huge plus and make it a lot easier to consider alternate presentational formats for TextBook.

I don’t know about Instiki, it seems way simpler but I am not RoR aware and I don’t even know how to install Instiki. I’ll dig and report… or ask those who know @txd

Last edited by davidm (2005-10-30 12:21:40)

NyteOwl · 2005-10-30 19:33:45

At the risk of being another <i>devil’s advocate</i> I’ll just add a couple of brief comments.

I’ll say up front that while I can see their usefulness in some areas I’m not a big fan of wikis.

I also wonder how the development team managed to do their initial programming and design, and coordinate with each other without documentation? You do comment your code and make function descriptions as you go I hope? This type of internal documentation is often an excellent framework to build user documentation on.

While they haven’t produced any in print form for some time, I invite anyone that would like to see an extremely useable set of software documentation and manuals to get their hands on some of Borland’s compiler manuals for Pascal or C. They are some of the most concise, explicit and easy to use manuals ever printed and an example that all document writers could benefit from looking at.

I’d be more than happy to help with documentation – once I figure out how this all works myself :-)

<i>Now if I could stop making typoes and having to re-edit my posts …</i>

Last edited by NyteOwl (2005-10-30 19:37:07)

Textpattern CMS

Textpattern CMS support forum

#16 2005-10-28 23:46:37

Re: [wiki] TextBook Issues (let's bring it together already)

#17 2005-10-28 23:54:47

Re: [wiki] TextBook Issues (let's bring it together already)

#18 2005-10-29 00:10:41

Re: [wiki] TextBook Issues (let's bring it together already)

#19 2005-10-29 00:16:38

Re: [wiki] TextBook Issues (let's bring it together already)

#20 2005-10-29 00:19:05

Re: [wiki] TextBook Issues (let's bring it together already)

#21 2005-10-29 02:06:08

Re: [wiki] TextBook Issues (let's bring it together already)

#22 2005-10-29 02:56:50

Re: [wiki] TextBook Issues (let's bring it together already)

#23 2005-10-29 10:23:11

Re: [wiki] TextBook Issues (let's bring it together already)

#24 2005-10-29 10:38:54

Re: [wiki] TextBook Issues (let's bring it together already)

#25 2005-10-29 10:44:45

Re: [wiki] TextBook Issues (let's bring it together already)

#26 2005-10-29 12:20:05

Re: [wiki] TextBook Issues (let's bring it together already)

#27 2005-10-29 12:42:02

Re: [wiki] TextBook Issues (let's bring it together already)

#28 2005-10-29 12:50:29

Re: [wiki] TextBook Issues (let's bring it together already)

#29 2005-10-30 12:19:24

Re: [wiki] TextBook Issues (let's bring it together already)

#30 2005-10-30 19:33:45

Re: [wiki] TextBook Issues (let's bring it together already)

Board footer