[wiki] User Manual

Destry · 2004-12-14 19:39:43

Remillard wrote:
<blockquote>Well, no, I actually meant to actually host it :).</blockquote>

Ah, that’s what I thought. You seemed clear enough.

<blockquote>“So, without further ado, Textpattern Documentation Project.”</blockquote>

ROCK-ON, Remillard!

(p.s., any chance of changing that link to read “Textpattern Manual Project” (?) I think it’s important to get the distinction down early so there’s no confusion. I’m mean documentation could be code documentation, Textpattern Resources documentation, etc. Circulating a clear focus on “manual” will be very helpful in dialogue.) – If we can get a true label hammered-down, we’ll be even better off. So vote people!

Damelon wrote:
<blockquote>“Yes, I love France too.”</blockquote>

Aint it true.

zmeigorin · 2004-12-14 20:03:39

And, Maybe a kind of Appendix C: Extending Textpattern? Describing plugins, maybe basic code layout and architecture, etc.

Destry · 2004-12-14 20:42:09

zmeigorin wrote:
<blockquote>“And, Maybe a kind of Appendix C: Extending Textpattern? Describing plugins, maybe basic code layout and architecture, etc.”</blockquote>

Hmmm…I knew this was going to come up sooner or later, and it’s good that it’s sooner. Personally, I don’t think this is such a good idea, for the very simple reason that it’s out of scope with what is trying to be achieved here.

I would redirect your attention back to the project outline at the head of this thread, and see #3 under the Basic Notions for a Textpattern User Manual. The idea here, as I see it, is a manual that you would get if you bought TxP and it came on a CD. The manual is only going to be addressing what is native to the current release, and it’s going to be talking to general users.

What you’re talking about is specialized information for the developer/programmer crowd, and that’s not the target audience for this manual. It might be the subject for another manual somewhere down the line (a developers manual for instance), but again, it’s out of scope here.

Now you did mention “basic layout and architecture.” That idea is already expressed in Chapter 5 of the structure, and it seems perfectly legite that this would be there, but only very basic info. No designer stuff, no CSS how tos, or whatever. All that is out of scope. Just the bare bones skeleton is all were talking about here, to get the new user on the right track.

Make use of the Textpattern Resources site for developer issues.

My two cents.

hakjoon · 2004-12-14 21:16:09

I think an extending TXP section as an Appendix, that could give some basic info and maybe point to a Developer’s resource is not a bad idea. After all if this does become a main doc people will come here looking for that info so it should at least point readers in the right direction. The extensibility of a system is also a selling point so it should at least be highlighted.

I can’t believe how much you guys did since I logged off yesterday.

Remillard · 2004-12-14 21:16:43

Well I appreciate the rock’ing and the on’ing, however frankly this is the easiest part. Without folks jumping in and actually doing some of the typing and thinking, it’s not going anywhere. It’s also not like this hasn’t been tried before. The Trac docs had few if any contributors, and there’ve been a few other attempts here and there.

I changed the link text. No problem there. i don’t mind trying to make this a little more formalized, but if you mention a 6-sigma process I’m going to scream and spontaneously combust ;-). I will only groan and kill the lights with a migraine if you mention ISO9000.

As far as having some sort of help documentation on plugins and hacks, I think it’s a good idea. I don’t care if it’s an appendix or a different “book”. However, I’m not sure TXP.org is the best place to collaborate on it. The TXP Resources is sort of a repository of things/news/etc. While it could house a manual, trust me, doing something even close to a manual in the little edit window is … daunting (and I should know after TXP-121-1.) The wiki allows a breakdown much like Linux HOWTO docs with a proper TOC and so on and so forth.

So, let’s see some folks get to typing. ;-)

Destry · 2004-12-14 22:53:17

Well, OK. My only concern is that now your shifting the focus from new user information to information about advanced topics. Is that a realistic goal for this effort. As Remillard just said,

<blockquote> “Without folks jumping in and actually doing some of the typing and thinking, itâ

Remillard · 2004-12-14 22:56:04

Even better, go do it on the page ;-).

Everything is about as set up as it’s going to get at this point. Wikiedit to your heart’s content.

Rem

alicson · 2004-12-15 17:07:12

gracious, i’m behind on this discussion. ok, well in i go..

part of the beauty of having the Textpattern Resources site hosted at textpattern.org rather than the temporary goodgrape.net/text location is that the site now is in its own space; not threatening my personal site’s bandwidth or space or anything (though that was never a concern..) My point is, there’s more than enough space there for the current directory of resources as well as a Textpattern manual.

Regarding the appendix C/expanded Textpattern stuff:

> zmeigorin wrote:
<blockquote>“And, Maybe a kind of Appendix C: Extending Textpattern? Describing plugins, maybe basic code layout and architecture, etc.”</blockquote>
> Destry wrote:
<blockquote>Hmmm…I knew this was going to come up sooner or later, and it’s good that it’s sooner. Personally, I don’t think this is such a good idea, for the very simple reason that it’s out of scope with what is trying to be achieved here.</blockquote>
> hakjoon wrote:
<blockquote>I think an extending TXP section as an Appendix, that could give some basic info and maybe point to a Developer’s resource is not a bad idea. After all if this does become a main doc people will come here looking for that info so it should at least point readers in the right direction. The extensibility of a system is also a selling point so it should at least be highlighted.</blockquote>
…i think it’s a good idea. i do think that we should focus on gearing to newbies first and foremost…

i had been envisioning the manual thing as… well, see, this is where it makes sense to me as a TextBook… if done correctly, it could have useful layers without being overly cluttered.. each chapter would focus on a different aspect of Textpattern… maybe chapters 1-5 would be introductory and have to do with the features of Textpattern, and installing it and becoming familiar with the admin interface and such. the next five chapters might have to do with intermediate usage of Textpattern… and much later chapters can start incorporating some of the tips/tricks/etc….with more complicated/familiar Textpattern language and stuff. those first five (or however many) chapters, though, would be the most important, i think, and should be most clear and maybe a bit separated from the rest. but i would see the rest be there too. and that’s also where i see the current resource site fitting in with the manual document/site/section; where those ‘advanced’ articles can be intelligently fitted together to form a logical progression in terms of useage.

question: once the final manual document/site/section is up, how changeable do we want it to be? i mean, in terms of anyone coming along and adding to it/changing it directly? or will it be okay to have a few main people maintaining structure and updatedness and content, with the general public able to add entries in a separate section and of course able to email suggestions and changes..? answer to this matters much.

i should maybe paste some of these thoughts in the wiki, neh? i’ll go check that out now…

Last edited by alicson (2004-12-15 17:20:01)

alicson · 2004-12-16 00:37:59

okay.
i’m gonna be honest… the wiki confuses me. i do tend to be reasonably good with intuitively picking up on interfaces and new apps, and the truth is i think i can find my way around the wiki pretty well..but it’s mostly through my own manner of stumbling.. i’m not sure everyone will have that kind of patience and want to work on it through this interface. —particularly if we want more than a couple people’s input in the beginning stages of composing this. that said, i have decided that the following two links are the main ones to look at/work with while using this wiki:

Special:Recentchanges, to see recent changes and find what was last said (and by whom)
Textpattern_Manual, which is the actual Manual itself, which is what we’re working on, right?

well, those links will be helpful for me, anyway, since they directly get me to where i need to go to see what’s going on. i imagine you do have to be logged in to get to them? (or is that just to edit?) but registering and logging in is not painful at all.

there is already a good amount of information laid out there, and it is accessible and editable and all those things are good. i’m more concerned about getting the content together and polished, than about the method of organization, and final presentation, at this point.

speaking of this point… where are we now? how shall we proceed?

i won’t be very helpful til i’m back from my trip (late January), but i’d like to try to help while i can..

wherever we end up composing this/working on it/finally posting it, i think it might be nice to continue a bit of discussion here in this forum, so that other, quieter Textpatterners can see a bit of what’s going on, and might be enticed to lend a bit of their input every now and then.

*edit: polishing textile a lil

Last edited by alicson (2004-12-16 00:39:36)

Destry · 2004-12-16 02:00:41

Alicson wrote: 
<blockquote>”…speaking of this point… where are we now? how shall we proceed?”</blockquote>

Good question. If anyone has been following along (and you probably have if your here, hopefully), then it should be pretty clear that this effort was made in good intentions, and for the purpose of filling a long past due need — formal user documentation.

I thought I had made a pretty thorough search in the forum to see if there was some other effort in progress, because if there was one, it wasn’t my intention to duplicate. We all have better things to do.

However, it turns out I missed a couple of important threads where Dean himself talks about a user manual effort he (or somebody) is is apparently working on. The revelation of which seems to be with the release of TxP v 1.0.

The threads where you can read about it yourself are…

<ul><li><a href=“http://forum.textpattern.com/viewtopic.php?id=1477”>Where are the basic instructions? Step A…Step B…Step C..?</a></li>
<li><a href=“http://forum.textpattern.com/viewtopic.php?id=98”>Documentation?</a></li></ul>

Naturally, upon discovernig this (today or last night, I’ve lost track), I immediately wrote Dean an email to see if I had in fact ran afoul, and to beg pardon if I had. I also asked for his words of enlightenment in return. The verdict is still out, and as such, it’s probably prudent to not get too revved-up with anything else until the verdict is in.

<hr />
EDIT: Well, taking a closer look at those threads, it seems that was banter clear back in February 2004, and the v 1.0 was actually the 1.0rc1 release (apparently that target was missed). So, maybe the new effort here isn’t dead yet.

By the way, assuming everything is fine to proceed, the wiki is only intended to get something going until a better place is realized, especially if nobody is happy with the wiki. (I too find the wiki to be very unfriendly, but it is a start until something else is clear.)

Oh, and the user manual, for this effort anyway, is now officially dubbed “TextBook.”

Last edited by Destry (2004-12-16 02:27:02)

Remillard · 2004-12-16 06:31:59

Just as a note, SDF is having trouble I guess. I can’t seem to get to it via web or ssh.

I have a brand spanking new Textdrive account, and will be moving the wiki there as soon as is reasonable (read: there’s a lot of information I just got e-mailed to me and I’m still sorting through it ;-)). I think TXD will be much better at handling the wiki backend code than SDF. More oomph.

EDIT: Well it’s back, but I think it’s still lacking oomph. The MediaWiki code is significantly complex.

Last edited by Remillard (2004-12-16 06:51:54)

Dean · 2004-12-16 11:54:27

Hey, this is great! I endorse it to the hilt, and I think MediaWiki is the right tool for the job. Shall we put it at textpattern.net?

Destry · 2004-12-16 13:23:08

Wha-hoooo! A Dean endorsement. I for one think that putting there would be good. Keeps the work…centralized.

Thanks for the shout, Dean.

Destry · 2004-12-16 14:04:26

I can’t seem to edit my posts in this thread. I can add a new post (obviously). I’m getting this error…

<blockquote>“Precondition Failed

The precondition on the request for the URL /edit.php evaluated to false.”</blockquote>

Gremlin?

Dean · 2004-12-16 14:27:39

try using forum.textpattern.com rather than textpattern.com/forum and see if that makes a difference.

Textpattern CMS

Textpattern CMS support forum

#16 2004-12-14 19:39:43

Re: [wiki] User Manual

#17 2004-12-14 20:03:39

Re: [wiki] User Manual

#18 2004-12-14 20:42:09

Re: [wiki] User Manual

#19 2004-12-14 21:16:09

Re: [wiki] User Manual

#20 2004-12-14 21:16:43

Re: [wiki] User Manual

#21 2004-12-14 22:53:17

Re: [wiki] User Manual

#22 2004-12-14 22:56:04

Re: [wiki] User Manual

#23 2004-12-15 17:07:12

Re: [wiki] User Manual

#24 2004-12-16 00:37:59

Re: [wiki] User Manual

#25 2004-12-16 02:00:41

Re: [wiki] User Manual

#26 2004-12-16 06:31:59

Re: [wiki] User Manual

#27 2004-12-16 11:54:27

Re: [wiki] User Manual

#28 2004-12-16 13:23:08

Re: [wiki] User Manual

#29 2004-12-16 14:04:26

Re: [wiki] User Manual

#30 2004-12-16 14:27:39

Re: [wiki] User Manual

Board footer