You are not logged in.
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
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.
not a critique, just feedback from a user:
really like zem’s dynamic tag generator
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.
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.
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.
No don’t mess with the Tag section. I use it as well. I think most experienced TXP users will only reference that section on a regular basis. They probably think they know what’s in the rest. ;)
I find the tag section helpful too and I have sometimes kicked myself for not using it after discovering that a tag had a very useful attribute that I just assumed wasn’t there!
In regard to the CMS vs. wiki argument, I think you could really use either, but the project would require some dedication, patience and organization (Destry can probably attest to this). Based on the fact that the Textbook project began as a wiki, I really hate throwing the baby out with the bath water. I haven’t looked at Instiki in any detail, but that may be the way to go.
I would be happy to “throw my hat in” as a writer/editor, but I would really want to make sure there was a proofreading/editing phase with a small, capable and manageable group of people who are dedicated and organized. Let’s face it: the TXP CMS is advancing very well because it has a strong, small core of talented and dedicated programmers (Alex, Sencer, Pedro, Dean, etc.).
Yes, the “community” is important too (identifying bugs, plugin support, feature requests, etc.), but an open source project only succeeds by having that strong core.
But programming and documentation writing are really two different things. I think good documentation requires a strong proofreading and editing phase before throwing it out there to the community at large. That is how you achieve a high level of organization. The community can still point out documentation “bugs” post publication, but I think many of those bugs can be stomped prior to the wiki publishing phase.
Maybe the solution isn’t in jettisoning the wiki for a CMS, but using a pre-wiki tool for small group collaborative writing/editing. I’m just throwing this out there for consideration, but maybe we should consider something like Writeboard for a pre-wiki phase in documentation writing. Or find a wiki that has a CMS-like ability to post for editing/approval phases without going live immediately. I also like the concept of versioning.
Alex brings up a good point regarding the excellence of the PHP Manual; it might also be helpful to survey some other “best of breed” documentation projects out there to discover what works and what doesn’t. I’ll start poking around.
Update: Oops. I see that Destry has sort of closed the thread after reading his post above and most of my comments were already covered by another writer or two. Grrr. I’m always late to the party.
Last edited by aesop1 (2005-11-01 05:33:37)
That a wiki might not be the approbiate tool for TextBook was discussed just before Textbook was set up. I remember that very well. I noticed people hesitate to login and learn the wiki-langugage with many other projects. So an Instinki might be a better tool.
As well i would support the idea to set up a forum section for TXP documentation. Just for 2 reasons:
Last but not least i like to make a suggestion concerning marketing strategy i made some good experience in the german txp community with. i kept on telling people: you get something for free and so i expect you to give something back – this is the Open Source policy, please keep that in mind
It may sound strange to the minority of you txp contributors, but you really have to sell an idea, bring the Open source policy into peoples mind and do not expect others to just contribute.
Last edited by alexandra (2005-11-01 15:18:10)
Yeah, I really think a forum for “documentation planning” (or something similarly indicative) would be a really good idea. You might get more great requests for documentation like this, but in one central location, rather than all over the place. Plus, as indicated already, the forum could have stickies at the top, one for each main resource (TextBook, TxP Resources, FAQs, etc) that served as places for heads-up information for each respective resource. Many possibilities of use for such a forum.
aesop1 wrote: Oops. I see that Destry has sort of closed the thread after reading his post above and most of my comments were already covered by another writer or two. Grrr. I’m always late to the party.
No, thread’s not closed, new ideas/comments are welcome, but I’m mainly seeing the same ideas getting repeated (more or less) so I thought I would start processing things.
Thanks again for everyone’s input…and your patience while I sift things down.