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

thebombsite · 2005-10-31 14:53:03

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. ;)

aesop1 · 2005-11-01 04:49:01

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.

-Matt

Last edited by aesop1 (2005-11-01 05:33:37)

alexandra · 2005-11-01 15:16:56

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:

only a minority is very active in this community. Many others only drop by, get some infos and disappear again. Most people never get the info that help is needed with documentation.
documentation is pretty scattered (worldwide) – we need a place to communicate and bring info and people together.

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)

Destry · 2005-11-02 06:47:06

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.

davidm · 2005-11-02 08:57:56

Glad to sea my idea was not way off :-)

Now did you get feedback from the forum’s admins about this ?
When will it be added ?

Jeremie · 2005-11-02 17:20:11

Who said TextBook was not a very basic (in the meaning of most essential need) ressource even for old hairy geek ?

Last edited by Jeremie (2005-11-02 17:20:32)

thebombsite · 2005-11-02 18:41:49

It wasn’t me. :)

boblet · 2005-11-03 18:21:40

personal perspective – I’m somewhat put off by the Wiki language, but my main barrier to greater help is a lack of knowledge. I don’t know enough PHP to be able to work things out from the code, and I’m not quite getting the ‘TxP way’ yet either. As an example I’m presently wondering what the differences are between calling a form to make, say, a list of recent entries using txp:article, txp:article_custom or txp:output_form (that’s not a request for an answer, just an indication of my ignorance on something that’s probably obvious to all of you ;-)

I’m trying to change/improve TextBook stuff that I know about, but it’s taking a while to get my head around how everything works.

peace – boblet

aesop1 · 2005-11-04 17:17:19

Hang in there, boblet. I think most of us can attest that it took us awhile to pick up on the usage of the various tags. This is also a challenge for the documentation. Tags like txp:article and txp:article_custom are very powerful and can be used in different ways. I’m still struggling to learn some of the new features of version 4.0.2—especially that new “pageby” attribute for txp:article. I’ve read Alex’s post about it twice and I’m still scratching my head.

This is oversimplifying things quite a bit, but for txp:article, think content, for txp:article_custom, think menus (and content, especially that out of current section scope), and for txp:output_form, think includes (but forms can include some txp tags as well) . . . yikes.

See how badly we need TextBook?

Destry · 2005-11-07 17:32:46

Followup coming soon…promise. Sometime this week for sure.

NXArmada · 2005-11-07 18:50:35

Textbook should stay its a great resource. Granted MediaWiki formating sucks but Textbook has helped me alot.

Mary · 2005-11-08 02:15:19

Have a forum.

I don’t think anyone wants to dump the wiki completely. I certainly don’t. I’ll repeat here what I’ve already said to others elsewhere:

From my perspective I think it just needs shuffling/adjustment/reformating/whatever, because obviously things are not as good (based on user feedback) as they could be. I think we’d benefit from a kind of split.

“official” docs

faq and any basic troubleshooting/diag. docs (I think that’s already a section under the faq, isn’t it?)
Chapters 1, 2, 3 (overview of main interface and explanation of general textpattern concepts, how tags and attributes work, sections, pages, forms, and so on, parts of the glossary)
Appendix A, E (basic tag reference, default forms and pages)
plugin development references, like plugin template and the plugin template example, basic list like the tag list, of the available plugin-specific functions (register tab, privs, etc) and callbacks.

wiki

Chapters 4, 5, 6, 7
Appendix C (migration)
tag usage examples, how-tos, walkthroughs and so on
“how to make a plugin”, helpful plugin tools, “best practices” and so on. my sticky thread from the plugins forum would fit here (sans the permissions info, that’d fit in the official docs), and it’d be nice for others to improve upon it, it being in the wiki rather than the forum

In other words, basic structured and/or technical info for the manual, more casual and in-depth followup in the wiki. That way its easier for the crucial info to remain accurate and up-to-date, and more relaxed and friendlier atmosphere at the wiki.

When I agree with Instiki, I mean its simplicity to use, the interface isn’t “scary”. We could still keep MediaWiki, just upgrade it, reorganize it and re-design it. Sure, a certain amount of new work now, but I think it would pay off later.

Textpattern CMS

Textpattern CMS support forum

#37 2005-10-31 14:53:03

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

#38 2005-11-01 04:49:01

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

#39 2005-11-01 15:16:56

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

#40 2005-11-02 06:47:06

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

#41 2005-11-02 08:57:56

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

#42 2005-11-02 17:20:11

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

#43 2005-11-02 18:41:49

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

#44 2005-11-03 18:21:40

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

#45 2005-11-04 17:17:19

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

#46 2005-11-07 17:32:46

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

#47 2005-11-07 18:50:35

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

#48 2005-11-08 02:15:19

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

Board footer