Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

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

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

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

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)

Offline

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

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

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

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

Offline

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

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

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

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.

Offline

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

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

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

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

Offline

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

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

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

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)


.: Retired :.

Offline

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

NyteOwl
Member
From: Nova Scotia, Canada
Registered: 2005-09-24
Posts: 539

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

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)


Obsolescence is just a lack of imagination. / 36-bits Forever! / #include <disclaimer.h>;

Offline

#31 2005-10-30 20:26:35

hakjoon
Member
From: Arlington, VA
Registered: 2004-07-29
Posts: 1,634
Website

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

I kind of liked the idea of a documentation forum where people could discuss and flesh out article ideas for the wiki. I know the point of wiki is to not have to do that, but I have very little confidence on my technical writing and sometimes being able to flesh out thoughts with others might help.

I find I spend a lot of time looking at textbook in search of something to contribute and it all seems to big for me to tackle when I have time (I’m in the ubernostrum camp. Writing is hard).

I also don’t think a Forum dedicated to a documentation effort is necessarily a bad idea. I like davidm’s thoughts on using it to bridge the forum and the wiki.


Shoving is the answer – pusher robot

Offline

#32 2005-10-30 22:10:24

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

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

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?

What you see is what you get. If we had more documentation, we’d publish it.

We all find chatty code comments unnecessary and cluttering. Well written code doesn’t need heavy commenting, just light annotations here and there.

Though we’re not going to clutter up the code with PHPDoc style @tags or big comment blocks, I’m open to the idea of extracting some information from the code. Early experiments here.


Alex

Offline

#33 2005-10-31 00:48:24

nardo
Member
From: tuvalahiti
Registered: 2004-04-22
Posts: 743

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

not a critique, just feedback from a user:

  • I use Textbook as a tag reference basically – what attributes can a tag have? where can the tag be placed? – I forget stuff, and appreciate this kinda clear and concise list
  • generally I use the alphabetical tag list (don’t much like the other categorisations) – could a link to that appendix go on the left-hand-menu? … and move info for ‘authors/editors’ to the bottom of the page
  • apart from that, I’ve used some of the SVN / localhostin’ info – but that’s all

really like zem’s dynamic tag generator

Offline

#34 2005-10-31 10:48:28

davidwang
Member
From: Malaysia
Registered: 2005-01-25
Posts: 38
Website

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

Hi guys, first up i just want to say that the Textbook has been a lifesaver for me many times over. like nardo, i use Textbook mainly as a tag reference. it’s even got a permanent place in my bookmarks toolbar. There are other gems too, like how to move databases from one host to another.

I love Textpattern but I have been tempted by competition like WP many times just because of the documentation. it’s more professional and that somehow gives the impression that WP is like a pro tool too. (luckily we know better). Anyway, my point is that a revamp is much needed not only to organise the documentation better but also to make Txp more accessible to newbies and those who are using it for mission critical projects, eg. client sites.

I would vote to keep Textbook on a wiki as i feel it works better as a collaborative platform where everyone can fact check and contribute. that being said, i have always found wikis to lack in implementation. i have tried using wikis a couple of times for my own purposes and somehow it always ends up stagnant. I guess it’s just not intuitive for most people. So perhaps, Instiki with textile which we are familiar with may prove to be better for us.

Last of all, I think what’s needed the most is organisation with the writers themselves. Perhaps destry could assign topics to particular writers. Before posting, a sub-editor will check the article for simple typos, grammer mistakes and mark it up in MediaWiki/whatever syntax. Then the article has to go through destry himself (the editor) or someone more familiar with the technical sides of things (like zem?) to ensure accuracy before finally publishing it. This is a 3-step process I have modelled on how news articles get written and published, and while it may be more work, but it is more structured and will provide the ‘motivation’ to write when an article has been assigned to a particular writer. Once published, the article is fair game and everyone can edit, fact check and add tips and tricks in the wiki.

sorry for the lack of coherence, just some ideas i want to squeeze off while rushing to leave the office.

Offline

#35 2005-10-31 13:50:29

ramanan
Plugin Author
From: Toronto
Registered: 2004-03-12
Posts: 323
Website

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

Just thought i’d chime in here too. Like Nardo, I use the Textbook solely as a Tag Manual. So, whatever direction you choose to take the manual, it would be nice if you kept the tag manual as it is now.

Offline

#36 2005-10-31 14:22:03

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

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

Just want to pop in real quick and say Thank You to everyone who has contributed to this thread. All feedback has been greatly appreciated.

I suspect it’s getting close to the point where whatever is going to be brought to light probably has by now, so I’m going to take some time and sift through all the feedback and produce a concise outline of the problems pointed out and match them with the various suggestions/opinions about what to do about them. I will also give some idea of where I think things might go based on looking at that outline, but I suspect there will be need for more fine-tuning questions, as well as another round of snowballs.

Anyway, just need a little time, hang tight.

@davidwang: Your thoughts are interesting, and though we probably won’t implement them directly as described (I don’t want to be assigning anything), I think there is something to be considered there that might tie-in with other ideas offered already, but I think it will rely on having this “Docs Planning” forum that has been suggested a few times or it probably won’t have teeth. I’ll elaborate later.

P.S. It’s pretty clear by it’s popularity that the Tag section is not going anywhere. The goal will be to make other sections of TextBook just as valuable over time.

Offline

Board footer

Powered by FluxBB