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

aesop1 · 2005-11-08 05:34:12

I think that’s a really good approach, Mary. It’s a good marriage of structured writing and community input. What do you think, Destry? (I think the guy who has been doing this thing for a while deserves some well-earned deference).

Last edited by aesop1 (2005-11-08 05:36:00)

alexandra · 2005-11-09 00:23:22

I agree.. good approach mary.

Okay, we did diskuss the forum issue long enough, didn´t we? who is setting it up?

Jeremie · 2005-11-09 03:54:05

It sound like the main issue – from what I remember at the begining of this thread – isn’t adressed.. several informations on different places. How a newcomer to the TXP world will find any informations at all ?

Mary · 2005-11-09 05:51:16

Jeremie said:

It sound like the main issue – from what I remember at the begining of this thread – isn’t adressed…

To quote Destry, in the first post, this thread is to:

…reply to some of the ideas being brought to light about TextBook in this thread”…

Jeremie said:

…several informations on different places…

That’s because its sorted by content type. It is on different websites because I-don’t-know. One guess would be because there is more than one person involved, each having a different goal, and each was started at different times.

Jeremie said:

How a newcomer to the TXP world will find any informations at all ?

Well, they could follow the links given to them. They are on every single page of the main site, as well as on the forum. If a person won’t make use of what’s right in front of them, then the question is: is there anything we could do to help them further?

Granted, the wording for the links isn’t necessarily illustrative. For that you’d need to go to the source, and say – in a loving way ;) – keep-it-simple-stupid, we don’t all “get” what you’re saying.

I’m kicking ‘round here, so I changed “TextBook” to “Manual”. Can’t think of anything more explicit than that. :)

thebombsite · 2005-11-09 06:45:31

You could change TextGarden to “Style Templates” if you want Mary. I know a lot of people will connect TextGarden with Zen Garden and think “styles”, but oddly not everyone has heard of Zen Garden. That might not sound realistic, but it’s true.

Destry · 2005-11-09 11:23:12

Thanks to Mary for creating the Documents Discussion forum. Personally speaking, and as people have mentioned already, this will serve greatly as a median between the people who like the forum, and the people who are not afraid of the wiki. What I hope to see happen in this new forum is any of four things:

Requests from anybody and everybody about the kinds of documentation they see being needed, whether in general or for a particular problem they have. A great example is maniqui’s post here, which by the way could be moved to the Docs Disc forum, IMHO.
By way of individual topics in the forum…we see a gathering process take shape where bits and pieces of very useful information scattered about the rest of the forum is roped together in one place. I don’t mean to suggest copy/pasting the text, or moving those threads, I’m talking about starting a well-titled topic, and then making posts in that topic with links to other places in the forum that have immediately relevant bits of info that could help with the creation of a full How To article focused on the topic title. This would be incredibly powerful and helpful for those who don’t mind doing the final writing, but can’t spend the time hunting and gathering the nuggets of gold. The two camps working together can do a lot here.
Further suggestions about how to shape documentation planning, whether it’s what kind of documentation is needed, how it’s created, where it is housed, how it is displayed/presented, and so forth. I.e., all ideas welcome. Ideally, we would try and organize ideas by popularity or quantity, but that might be too much to expect.
There is a lot of dislike for the tone/stuffiness of wiki help pages, (I guess the auxiliary pages like user accounts, language support, collaboration procedures, etc), so those pages could be discussed and redrafted here. (Pick a page and break it down, someone will use the changes in the wiki.)

Last edited by Destry (2005-11-09 12:10:36)

Destry · 2005-11-09 12:43:27

I was going to put up an ordery outline of all the ideas put forth in this thread but I just can’t seem to get too that, and perhaps it’s not necessary anyway. Instead, let me recap what seems to be the general problem and the steps that seem sensible to take in the immediate future.

Wiki or No Wiki

At least for now, we’re sticking with the wiki.

This seems to be more or less a split position. However, most of the arguments presented about not using a wiki seem to be of personal preference, rather than what is good for the community and the objectives of TextBook as a whole. Many times I brought up the fact that the wiki is now supporting multiple languages, which I believe is one of the most important aspects of this community (internationalization), and not once did anyone bother to provide an alternate platform solution that would ensure we maintained that (as far as I know, TxP can’t support multiple languages in one install). In my point of view that is reason enough to stay with a wiki.

That’s not the only reason, however, which Jeremie has been good at pointing out…a wiki is simply the right way to go if you are going to collaborate easily on document drafts. If we designated only a handful of people as ever doing the writing/editing (like what goes on in the FAQs) that would be one thing and perhaps a CMS would be the way to go (though we would still have the language support issue), but that’s not what we are doing here, we are essentially opening the doors for everyone, of all languages to help create documentation, and that’s the way it should be.

Main Problems

Of the problems mentioned, most seemed to be centered on three things:

the unfamiliar syntax of MediaWiki (and it is ugly, no doubt),
the official tone/stuffiness of the help materials,
and the overall organization and presentation of wiki content.

Since we are sticking with the wiki (at least for now), we should address each of these issues as much as possible.

Obviously the first issue is not going to be immediately remedied. (Instiki is still a possibility in the not-too-far future; however, unless it jives with the multi-language support, then it’s not an option). As for the wiki syntax, some people will get it, some won’t; I guess the thing to do is create other types of contribution opportunities for those that don’t. One such way to contribute is in the Documents Discussion forum (see my previous post for ideas about how).

As for the other two issues, we can certainly do something about them, and we will.

I would ask that people not get too hung up on this idea of “official” documentation. It was probably a mistake to ever introduce that word at whatever point in time it was. The best way to remedy that issue to get rid of that word whenever possible. If you see it somewhere, whether in the wiki or here in the forum (with the exception of this thread), then edit it gone. If you can’t do it, point it out to someone who can.

Also, I would encourage that anyone who has a problem with a particular page in the wiki as being unsavory in tone or vibe…take it upon your self to write something more along the lines of what you think; but again, do it as a documentation collaboration effort (see #4 in previous post). Jeremie, you mentioned the TextBook Collaboration Procedures page is 7337 bytes long and a lot to digest. I agree with you. Why don’t you take up the challenge and write something more concise without losing the meaning. ;) (Thing is, the page is not meant to be memorized, it simply serves as a reference for each of the collaboration topics it presents, and each topic is easily accessed from the page’s ToC at the top of the page. Just one way of looking at it. I think the real key is linking to the individual topics better; we’ll work on that.)

As for organization and display; this might be the biggest one of all, and perhaps when addressed will solve many of the little issues people have. People had mentioned the WP Codex, I looked at it, it’s fine, not perfect. We can do something similar and still meet the objectives of TextBook better. Please resume following at TextBook wiki redesign planning

I would like to start shutting this thread down now.

If you want to discuss any singular concepts brought up in the history of this thread, I recommend you start a new topic in the Documentation Discussion forum about it. Here are possible ideas:

Instiki evaluation for documentation
Pursue Mary’s idea more (as for myself, I’m not clear what she’s suggesting exactly…two platforms? Seems like the wrong direction, but maybe I just don’t understand.)
why is water clear?

Last edited by Destry (2005-11-09 13:11:38)

andreas · 2005-11-09 12:53:21

Sounds good to me as well.

thebombsite · 2005-11-09 15:06:44

Destry, I shall be doing “how to’s” over at FreshlyPressed from time to time. I don’t know whether they are good enough or even suitable but if you want to copy/paste any parts of them feel free.

Destry · 2005-11-09 15:21:58

I’m glad you brought that up Stuart, that’s a point I forgot to mention.

Everyone: it’s not immediately essential that the actual text be added to TextBook from the get-go, but rather there is something filling the void (as it were) and marking the spot. I’ve begun using a method along these lines myself, see here.

EDIT: Yes, this is somewhat like the process the Resources Site uses, but the difference is that for TextBook a more generic version of the article does get moved to TextBook, eventually, which is thereafter the property of the community to edit as needed. (Generic meaning it’s rewritten to not be specific to a Web host, operating system, etc.) In these cases, I will always maintain my Journal article first.

Last edited by Destry (2005-11-09 15:27:45)

thebombsite · 2005-11-09 19:41:19

OK. So do I need to add the page/link myself? If so I shall need a login. In the mean time I shall try to keep the articles as non-generic as I can. :)

Last edited by thebombsite (2005-11-09 19:42:18)

Mary · 2005-11-09 23:42:35

Okay, pursuing individual doc-related topics in their own thread. Closing this one to “encourage” (okay, dictate) that. ;)

Textpattern CMS

Textpattern CMS support forum

#49 2005-11-08 05:34:12

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

#50 2005-11-09 00:23:22

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

#51 2005-11-09 03:54:05

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

#52 2005-11-09 05:51:16

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

#53 2005-11-09 06:45:31

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

#54 2005-11-09 11:23:12

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

#55 2005-11-09 12:43:27

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

#56 2005-11-09 12:53:21

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

#57 2005-11-09 15:06:44

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

#58 2005-11-09 15:21:58

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

#59 2005-11-09 19:41:19

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

#60 2005-11-09 23:42:35

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

Board footer