[wiki] Documentation Distribution

Destry · 2005-12-31 11:53:05

(I start this thread based on some relevant points raised by Locutionist, there, but which should really be discussed here.)

Locutionist wrote: (1) The second problem I ran into was difficulty wading through the documentation. Information is spread across four separate websites (2) and tends to assume users have a great deal of familiarity with Textile, (3) and with Textpattern’s conceptual model. (4) I know it is tempting to just assume users are stupid; (5) but as a tech writer, if I were assigned management of Textpattern’s documentation the first thing I would do is create a portal that lays out Textpattern’s conceptual model in nontechnical language, and link to everything from there.

(numbered your quote for clarity of response)

I agee with the distributed nature of TxP documentation, and I’ve said as much many times before, as people may attest (for example). If more people got behind TextBook, like yourself, making worthy contributions, this wouldn’t be such the problem you point it out to be.
Textile could be a topic pursued in depth in TexBook. I even had a placeholder in there for it, but nobody wrote. I can easily add it back and you can get writing/editing (or hyperlinking).
I agree, what little has been written about semantics (another big word) has been pretty backend and lacks context from a user side. I’m about to publish an article of my own that tries to address this very issue. It will be on my Web site, where I hope to get feedback on it before drafting something down for TextBook. When ready it will likely ~~take the place of~~ be referenced in ~~what is here~~, Textpattern Semantic Model (which could probably use a simpler title).
“Stupid” (?) I think what you meant to say is smart, which would imply bad documentation because writers assume users already know about Textile, etc. In any case, as a technical writer, you as well as anyone should know that writing clearly about complex concepts — and to specific audience — is not easy work. It takes a conscious, hard effort, and likely many drafts. Developers and the 17-year old kids aren’t going to do that, or know how.
My position, from TextBook’s very beginning has been that it serves as the primary information source, and it can easily do that. I would argue that we don’t need another portal (we have the Resources Site already, which is exactly a portal), we just need people to write, and need more people with good editing skills (like a TCer) to edit and organize the information. TextBook can easily serve as ground zero (along with the FAQs) and people with the right understanding (perhaps like yourself) can edit the growing content to point to exteranal resources as it may be in context to a given topic. It’s no harder than a hyperlink, and you don’t need some whiz-bang platform for that. I’m working on all this with TextBook, shaping it slowly, but it takes a lot of effort and time, and for one person…well. So, get a TxB account already and put your fingers where your suggestions are. At the very least, get involved with the Document Discussion here more. ;)

hcgtv · 2006-01-01 00:01:33

Destry,

Being so new to Textpattern, I wouldn’t know where to start contributing to the docs, but I’d like to help out. I guess it’s hard to jump in not knowing what may be needed or being afraid to mess up something.

Are there articles, sections, etc., that you want people to work on?

Also, on the editing side, what needs to be checked?

Destry · 2006-01-01 19:24:51

Yeah, good point. These details seem to be needed. I’m trying to figure out a way to help bring these notions to light better, but also by introducing a method that more or less has community blessing. It’s not an easy thing to do, and nobody seems to want to offer ideas of their own.

As for what to write, here’s one place to start: 6sigma has offered this wish list of topics for TxB docs. I wish he had prioritized, but use your best judgement as to what’s likely more needed. Aside from his list, I think anything having to do with using TxP Tags in clever and useful ways is going to be good information, and in that respect I would consider something being brought to light in the Tag Examples forum.

As for editing, that’s a bit trickier. If you’re not sure, then I would just focus on the writing part and let someone else follow up with editing. A large part of editing in a wiki is knowing how to link different pages up effectively, how to break a given page into logical sections, how to rewrite paragraphs to be more concise and clear, how to provide the extra and useful details that the initial author didn’t consider (or think is important), etc. There’s also the little stuff like correcting spelling, capitalizations, puctuation, etc.

It’s not easy, to be sure. Most people will simply be content contributors, a fewer number of people will directly or indirectly find themselves doing editing. It just happens. In any case, anyone who is thinking about editing should get in the habit of following new pages and changes using the methods describe in this thread …it’s the only way to keep up.

Destry · 2006-01-07 19:59:47

Destry wrote: I agree, what little has been written about semantics (another big word) has been pretty backend and lacks context from a user side. I’m about to publish an article of my own that tries to address this very issue. It will be on my Web site, where I hope to get feedback on it before drafting something down for TextBook. When ready it will likely be referenced in Textpattern Semantic Model (which could probably use a simpler title).

Posted: Understanding Textpattern Building Blocks. Meant to be the first of a two-article series, and targeted to people new to Textpattern. Not sure I’ll put it in TextBook, but I have referenced it in the Textpattern Semantic Model page, here.

andreas · 2006-01-07 20:06:14

Wow, Destry. This looks promising. But I have to get something to eat first before I will work my way through it. As you’ve noticed, I still haven’t started shooting screens — there always seems to come a lot of work and life between the TextBook and me but I’m going to do it. Promise.

hcgtv · 2006-01-07 21:47:27

Thanks Destry.

Let me get a cup of coffee and take it in.

hakjoon · 2006-01-08 01:59:37

I have been thinking that general topics like this are exactly what has been missing.

I was looking through the Movable Type Docs and and they are quite good. Specially the section on templates and layout They really help you get started on using MT to run a site. I’m hoping to write something kind of along the lines of “templates and layout in textpattern” that could explain how tags work, common attributes, how they interact with forms etc. But I’m thinking of it as more of a tutorial then a high level doc as you have written.

Do you think it would be redundant with what you are planning to cover in the rest of the article?

Destry · 2006-01-08 11:02:36

My aim for the second article is to map the building blocks to the admin interface and really cross-reference with TextBook. This means I really want to get the site admin pages in TextBook up to date and sharp looking with screen shots. As to not be overly redundant with the TxB site admin docs, I will try and provide insight to things that are a bit out of scope of simply describing admin features — the inside understanding, as it were.

I would say what you’re after, hakjoon, is still wide open. There are so many sub articles that could be written, especially about layouts and tag use and such. Go for it.

6sigma · 2006-01-08 14:02:29

Destry, your Understanding Textpattern Building Blocks is a tremendous effort and an incredibly valuable resource. Thanks for taking the time to provide it.

Textpattern CMS

Textpattern CMS support forum

#1 2005-12-31 11:53:05

[wiki] Documentation Distribution

#2 2006-01-01 00:01:33

Re: [wiki] Documentation Distribution

#3 2006-01-01 19:24:51

Re: [wiki] Documentation Distribution

#4 2006-01-07 19:59:47

Re: [wiki] Documentation Distribution

#5 2006-01-07 20:06:14

Re: [wiki] Documentation Distribution

#6 2006-01-07 21:47:27

Re: [wiki] Documentation Distribution

#7 2006-01-08 01:59:37

Re: [wiki] Documentation Distribution

#8 2006-01-08 11:02:36

Re: [wiki] Documentation Distribution

#9 2006-01-08 14:02:29

Re: [wiki] Documentation Distribution

Board footer