Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#13 2005-10-28 23:18:47

davidm
Member
From: Paris, France
Registered: 2004-04-27
Posts: 719

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

@destry : thanks, much appreciated but I have to admit I don’t contribute as much as I would like to TextBook…

If I am not mistaken, the idea *was*, from the beginning, to move the wiki to a txp install someday.

TOOLS – I HAVE THE SOLUTION : WIKI + TEXTILE = INSTIKI

If we’re talking tools (which for me are not the biggest part of the problem), I agree with Jeremie and Destry this should be handled by a wiki, for one simple reason : to handle revisionning. Does MediaWiki have complex syntax ? Yes. But as Destry pointed out, it does have multilanguage support, Textpattern does not. Is it possible to manage documentation with a CMS, maybe better than a wiki ? Yes, if you have a limited number of contributors and don’t care about revisionning. A wiki is self regulating well when you have enough regular contributors.

If we’re talking moving TextBook to something else <span style=“color: #990000”>I have the solution to the wiki versus textile problem : a wiki which handle textile natively;. It’s called INSTIKI and the guys@textdrive now very well about it :) (see http://instiki.org)

There goes the textile vs wiki syntax argument, plus Instiki seems flexible enough and the folks@textdrive are more than qualified to set it up.

What do you say ?

THE PROBLEM : NOT ENOUGH CONTRIBUTORS = TIME CONSUMMING FOR FEW CONTRIBUTORS => LIMITED CONTRIBUTION

The title sums it up : I most definitely don’t spend enough time working on the wiki. How come ? I am motivated, and for the most part, able to do the job. The thing is, for any consistent content I have to spend quite a bit of time thinking, defining, structuring information to be able to write content that is (hopefully) clear and concise. The problem is to keep motivation you have to “see” things move forward, that is fast enough to think your contribution will make a difference and help achieve building this great project.

This is where things are not going well, I have discussed the reasons above In a way, the very logo of textpattern is about craftsmanship, and in this regard we could be tempted to say “…well, textpattern can not be captured by a documentation, help on the forum is so responsive : who cares about doc ? any thing I want to do with textpattern I can solve with the help of the community…”.

I don’t think this is true. Of course like any other things, doc will never provide true knowledge of the subtleties of txp, but it will help start from somewhere, and TextBook is somewhere I personnally already refer to (and yeah, rstiletti’s work on tags is a good example, thanks Rick). Plus, textpattern is not only used by webdesigners or skilled people and contextual help is not always enough. (Wait : just got an idea while writing this last sentence : what if contextual help pointed to the appropriate wiki page with a “more…” link ?)

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. As far as I am concerned, I’d like to discuss some issues, approach on how to go about this or that in the wiki : so far this was done though the discussion page (but not enough people going there to contribute), or with some very dedicated people via mail. This could be a link between forum and wiki.

What do you think ?

Last edited by davidm (2005-10-28 23:56:49)


.: Retired :.

Offline

#14 2005-10-28 23:42:43

Jeremie
Member
From: Provence, France
Registered: 2004-08-11
Posts: 1,578
Website

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

For TextBook, I don’t have personnal issue for the MediaWiki syntax. I can understand some have, and I can understand it’s a little odd not to have Textile handling the syntax (but on the other hand, Textile had/has issues with code formating and input); but I don’t.

And even if MediaWiki has other issues (not dashboard, no admin panel, and may be overkill on some aspect) I don’t push forward a software change (or the other way around for that matter… it’s Destry call). But it is a solid product, and have a very good base and potential future because of the Wikipedia project. It ain’t going to disappear.

I do believe that a wiki is important, for both reasons said :

First, if TextBook has manpower issue, we should do everything to appeal more to potential writers, and to help people digging in. Not the other way around.

Second, versionning and history are important.

Offline

#15 2005-10-28 23:44:50

zem
Developer Emeritus
From: Melbourne, Australia
Registered: 2004-04-08
Posts: 2,579

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

this should be handled by a wiki, for one simple reason : to handle revisionning

Again, the devil’s advocate asks: are those things really used in practice?


Alex

Offline

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

Jeremie
Member
From: Provence, France
Registered: 2004-08-11
Posts: 1,578
Website

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

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.

Offline

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

davidm
Member
From: Paris, France
Registered: 2004-04-27
Posts: 719

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

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…


.: Retired :.

Offline

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

zem
Developer Emeritus
From: Melbourne, Australia
Registered: 2004-04-08
Posts: 2,579

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

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.


Alex

Offline

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

Jeremie
Member
From: Provence, France
Registered: 2004-08-11
Posts: 1,578
Website

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

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)

Offline

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

Jeremie
Member
From: Provence, France
Registered: 2004-08-11
Posts: 1,578
Website

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

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.

Offline

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

Mary
Sock Enthusiast
Registered: 2004-06-27
Posts: 6,236

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

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.

Offline

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

Jeremie
Member
From: Provence, France
Registered: 2004-08-11
Posts: 1,578
Website

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

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 ?

Offline

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

ubernostrum
Member
From: Lawrence, KS
Registered: 2004-05-05
Posts: 238
Website

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

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:

  1. “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?”
  2. 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?”
  3. 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.


You cooin’ with my bird?

Offline

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

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

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

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.

Offline

Board footer

Powered by FluxBB