[wiki] A New Textbook

hcgtv · 2008-08-04 12:56:18

Destry wrote:

Carry on.

zero · 2008-08-04 13:09:38

My version is not meant to be additional. It is all or nothing. The community will decide. If it becomes The Textbook it will move to textpattern.net. If not it will be binned. It’s got robots disallow by the way, so no dissolution of content.

If if becomes Textbook, there won’t be a great need for Hakjoon, but some help will be needed with permissions in the first instance. Also with setting it up, so there is some kind of cross-checking with forum registrations, similar to as it is now. Most of it the site will be outside the document root so security should be a minimal problem.

zero · 2008-08-04 15:04:53

Ruud, Jonathan

I’ve altered the navigation somewhat. Is this more like it or were you thinking of something completely different?

The 101, 201, 301 etc are namespaces and changing them would cause great upheaval but could be done if it is essential. What is it about those numbers that you don’t like? If it’s because you want something more meaningful or instantly recognizable, has my change helped? If not, what alternatives do you suggest?

Note, I’ve put the language codes at the bottom because having both lang and nav at the top looked bad. I figured once someone has chosen a language they will navigate via the breadcrumbs because that keeps them in the same language. So language choice will be mostly a one-time thing. Also 70% of txp users use English (someone mentioned that figure on here before) so it’s better for the nav to go at the top because it goes to English namespaces only. With some php magic, ie if someone made a plugin, it would be easy, I think, to make it so the nav titles changed depending on the language namespace. As you can already see, this is done with the interface buttons, so I don’t think it’s much of a jump to extend that to the nav. I think I could do it myself with copy/paste hacking but I’d rather not mess it all up when it’s probably easy with a plugin. It would improve usability and friendliness a lot, methinks. Anyone interested?

Btw, I’ll be very interested in your IA and nav, Destry, and yours too Bert for that matter, if you’re going to extend your current system. I confess that I don’t really know what IA is, but guess it is how the information is organised so the site is most easily used, which is always interesting. If it isn’t that, then I am going to learn something! Please don’t let assumptions or lack of cohesion get in the way of joining in the discussion.

jstubbs · 2008-08-04 16:23:48

Some comments:

“Welcome to Textbook for Textpattern!” – better to say “Textpattern documentation and help”, or something similar
101 etc is quite bad, not sure what you mean by name spaces…
Tag should be more specific, something like “look up tags” or similar (note you have a listing of tags for 4.07 which is not out yet)
In fact, I would change all the headers. For example: 1. Basic concepts 2. How do I? 3. Administration 4. Development 5. Reference
You could add Admin tabs to the Administration area

Hope this is helpful.

zero · 2008-08-04 17:20:38

Thanks for replying Jonathan, it helps me understand you a bit.

1. As we may all have different opinions, perhaps others input would help in coming to the best introductory title.

2. Twice you’ve said 101 etc is quite bad but not yet given a reason why. I think it’s quite good so who is right? Namespaces are like the section names, pagenames are the article names – both appear in the breadcrumbs. 001, 101, fr, de, wiki etc are namespaces. Deleting or altering them is a lot of work. You cannot have a namespace called, for example, ‘basic’ and then use ‘basique’, ‘base’, ‘basika’ or whatever for other languages. It has to be the same one or language translation of the same article will not work right. So 101 etc is great because everyone knows it in every language.

3. OK, I like the active verb and it fits with Start Here and Learn More

4. There’s so much content on Textbook that compartmentalizing it is difficult because of what should go where most logically. ‘Basic concepts’ only describes part of the contents of ‘Start Here’, ‘How do I?’ is ok for tutorials but there are and will be other things to go in ‘Learn More’. Admin only covers certain things, as does development and reference. So can you see the problem? This is why something neutral like 101, 201 etc does not mislead or cause confusion. I can see that the number progression might cause someone to believe it gets steadily harder when this is only partly true and perhaps 101, 201, 301, 401, 320 might be better. As I’ve said before the numbers are understood by all languages. They are also short and sweet, which is better for breadcrumbs and for scanning text. Still think 101 etc is bad?

5. Good idea, extra links in relevant places are always helpful.

ruud · 2008-08-04 18:08:55

Regarding the points raised by Jonathan:

Yes, I agree. No need to say welcome… mentioning documentation and help instantly makes it clear what the user should expect to find here.
001, 101, 201… I don’t like ‘m for two reasons:
1. the numbers remind me of a good old fashioned linear book that has to be read in that order (don’t get me wrong, I love reading books; just don’t think the format is good here).
2. when I see 201 as a navigation link at the top, I have no idea what that links to. It doesn’t describe the contents of the link.
“Tag” would fit nicely as a chapter of its own: Tag Reference… or inside Reference.
That makes a lot of sense (to me). What I find difficult to understand with “learn more”, intermediate and advanced is that the user is expected to know which things are easy or advanced use of TXP. I think in reality the user wants to do something and is primarily interested in finding how to do it. Perhaps it wouldn’t hurt to give some indication (in a howto/tutorial section) of how difficult a task is, but that’s only interesting once you’ve actually found it. For example, I would think understanding textile and grasping the concept of categories/sections falls under intermediate/advanced, while installing TXP is relatively easy and would be in the “start here” section, since that’s what you typically do first before you can actually use it.
Admin tabs seems to be a mix of a reference guide for all admin side features and an explanation of concepts. Difficult to fit anywhere in the chapter list on the left side.

I’m not sure how well this would fit in the design, but perhaps the Tag reference could be a small set of links just above the Admin Tabs column on the right:

TAG REFERENCE

alphabetical
organizational

PS. I’m mostly wearing a ‘user hat’ in this discussion. I don’t care who uses what type of wiki for Textbook as long as it’s ends up as a fantastic and easy to use collection of documentation from the user point of view.

jm · 2008-08-04 18:59:14

- I agree with Ruud – the numbering system is not descriptive. >101 is no longer self-explanatory. Alternate namespaces:

101 -> Intro (/intro)
201 & 301 -> Tutorials (/tutorials)
401 -> Development topics (/developer)
501 -> Reference (/reference or /ref)

zero · 2008-08-04 19:26:37

Done
OK, I’ll make one last stand for 101 etc. First, for newbies, it is meant to be read in that order, at least 101 is, then they’ll search around. Secondly, 201 now has meaning at the top because ‘Learn More’ is with it. In the breadcrumbs it also has meaning because all you have is 001 > 201 > article-name when you’re reading an article, so you know that 201 will take you back to where you just came from. If you landed via Google, 201 won’t make sense I agree, but you would look at the top line and navigate from there, so no problemo. Please believe me that learning the numbers is very easy, almost instant. For me, navigation is actually easier using just 101, 201, 301 without the descriptions than it is with them. They are closer together, easier to recognize instantly. But I’m used to it of course. I really do believe everyone would navigate with them just as easily as with words after a few goes. For complete newbies, no, but for anyone who’s used it 3 or 4 times, the numbers are a cinch and I think they are worth sticking with.
Tag is already a chapter of its own. It doesn’t have a number because it’s a 3-letter word and is central to txp so I think it should stand on its own.
Installing is already in ‘101’ although there’s a link to it from elsewhere. I hope I’ve put everything essential to beginners in 101 because that was my intention. I hoped that the Learn More list on the front page would give enough of a clue as to what to expect in that section. The tutorials there are very simple to do and the only reason they are not in 101 is because they aren’t essential for understanding how to get going with txp. A person might want something admin or reference before needing those tutorials, so I appreciate how Intermediate and Advanced aren’t ideal. Perhaps Administration, Development and Reference are good after all, so long as ‘& More’ is added to them, at least on the respective content pages themselves. Is How Do I? better than Learn More, though, or Basic Concepts better than Start Here? It would be great if someone could come up with one-word alternatives that fit the bill. Just seen your post, jm. ‘Intro’ is short and sweet. I still think tutorials is too narrow though.
I put the Admin tabs in 101 and on front page because they need to be understood early on. Most people can pick up how to use them intuitively I should think, and I was tempted to drastically cut down the descriptions, but the concepts and finer details are there in case anyone needs them.

I don’t see how your tag reference, alphabetical, organization idea would help. Just click on Tag and it’s all there plain to see. For yourself and users who only use txb for tag reference, just click on the link at the top of the page, no need to scroll.

Great that you’ve got your ‘user hat’ on, Ruud. I much appreciate your time and effort to try and get this thing right.

jm · 2008-08-04 19:48:48

I disagree – tutorials is generic enough to encompass multiple articles. The /tutorials page can have headings that sort articles by category, but the root namespace would still be “tutorials.”

I think the problem with linear organization is users won’t head to the Textbook to learn all at once – they’ll go to look up a tag or feature. However, you could create an introductory article that links to existing articles with your 101, 201, whatever format as headings.

Gocom · 2008-08-04 20:09:10

zero wrote:

For complete newbies, no, but for anyone who’s used it 3 or 4 times, the numbers are a cinch and I think they are worth sticking with.

But initially, you have to be able to make the users read/click those odd numbers 3 or 4 times. Also, I’m with ruud: reading documention is faster when you can pick what you want to read.

Remember that there are more technical, faster to learn and smarter persons like experienced programmers that possibly start using TXP as the motor of their personal chocobo blog. They know how to write code, how to install things and how to learn to use things, but they don’t know all the tags or opportunities or where they can find them. Therefor, more descripting names are really fucking good not actually bad.

Btw, how many would even use textbook many many many times? It’s just docs.

So 101 etc is great because everyone knows it in every language.

Do we? :D Then my friend and a random dog are stupid…

Last edited by Gocom (2008-08-04 20:11:15)

zero · 2008-08-04 20:09:14

OK, gotta go now, but Intro, Tutorials, Tag, Admin & More, Development & More and Reference & More are agreeable to everyone?

zero · 2008-08-05 16:17:20

Yes, let’s get some facts straight, Destry, now you’re calling me shifty and other things.

Since your return you’ve made it clear where you stand, I’ll give you that. As you say here and here and in more recent posts, you will design Textbook your way whether we like it or not. Take it or leave it or you will walk away. Clearly not interested in what is best for Textpattern but solely concerned with laying your concepts on us or nothing at all. And do you like laying your views on us! You certainly don’t mind spending your time if it’s to expound your views! (Another example)

“I don’t think I could be more straightforward without looking you in the eye. The fact you think I’m not is pretty funny to say the least” and “I’m not reading into your words” you say. Oh really? I first noticed the opposite here. In the comment before it I had made a general statement but you chose to twist it and imply I was making assumptions about your words, when I did no such thing. There’s the snide remark slipped in about subjective opinions too – you like those little snide remarks don’t you? But I ignore that and put it down to your possible tiredness or something. But I start to wonder with this comment where you do NOT hear the overlap between me and Stuart. Again there’s a dig about my not-sensible (but sensible to me) suggestion. Then you say I am already putting target words on the table like cms or blog, but I never said that, except in a different context. Just small things which can be ignored if they are out of character. But are they?

You start the textbook architecture thread asking about Reorg and Reorg Temp on Textbook. “I’m not sure what the objective difference is. Which one should be focused on?” you say. If you had read them you would have known. Those were my first attempts to organize existing Textbook articles and with you being the IA expert and all, I thought you might have been interested. But instead of discussing those on Textbook, you just mention them on the forum and then your first post becomes another exposition of your knowledge of MW. In my reply to your question I answer your question and try to open up the discussion and you answer some of it. But you completely ignore what I’ve done on Reorg, which is crucial to get right. So I could only conclude that you have your ideas and don’t want to discuss them (which is reinforced by your response to this very thread we are in now – you’re not letting us know what you are doing are you?)

But back to textbook architecture and my next comment where I clearly state my opposition to a left sidebar. Your response is interesting! I say … “Are you saying there has to be a sidebar?” You say…. “From a technical standpoint, no, there does not have to be a sidebar. From a logical standpoint, yes, there should be a side bar, and I agree with you that it should be simplified to only the main categories representing the first-level Txp user content.” See how you put words in my mouth? I said if there has to be a sidebar , you say there hasn’t but you expect me to accept there has to be from a logical standpoint, and then make out that I am with you on having a left sidebar for main categories. You then say a couple of times there will be a left sidebar, thus effectively dissing my opposition to it. You then say you have ‘a pretty good vision now of the home page layout’. So there you are again, implying quite clearly, you are going to do it your way and any opposing views will be brushed aside.

In my reply I try to elicit what you understand by categories and which direction you are taking your design. You said one thing then another so I wanted to know what did you really mean? I also give suggestions as to these categories, to see if I can get a real answer to a real question from you. In response, you do not answer directly but imply I need educating and give several links. You slag off my concerns about content being buried with one word replies and then say you don’t want to discuss ad nauseum.

So, it’s OK for you to write many long posts but not OK for others to discuss opposing views? That is too ad nauseum for you but it’s OK for you to bore the pants off us with your views? It’s OK for you to spout stuff you’re going to do, but you’re not going to get your hands dirty and show us anything real or practical until it’s a done deal? It’s OK for you to come back after 2 years, play the IA and design expert and suggest my main usefulness will be cleaning up the content of Textbook, most of which is your mess?

I have come across several people during my life who do not give straightforward answers to straightforward questions, who read their own meaning into what I say, who accuse me of being the things they are themselves. I have learned to avoid them or risk being manipulated into things I would rather not do. You are another such person. Prove me wrong with your actions!

And to answer your statements above:
1. Everyone should now see why I did it that way and who is the shifty and disrespectful one.
2. My mistake, I thought you designed it too.
3. You should take that back now.
4. I am quite ready to be shown how great MW can be, although to get a quick wiki up, DW served my purpose perfectly.
5. Confucius he say: He who smelt it, dwelt it

I hope to hear your practical suggestions to practical problems posed in this thread such as namespaces. I look forward to seeing your MW redesign complete with left sidebar and WP influence. I do not look forward to waiting at least another month to see any of it, however. You’ve gotta do what you gotta do but I hope you might let the community behind your closed-doors project of the public Textbook. We can compete and co-operate at the same time if you do that to produce something excellent – much fairer than dumping a fate accomplice (sp?) on us all, or don’t you agree?

Last edited by zero (2008-08-05 16:23:36)

zero · 2008-08-05 16:39:47

I’ve made some changes again. Is it OK now?

Ruud, I only realised after I had replied to your post that Tags could be seen as part of 201. I hadn’t previously noticed that with Tag not having a number, someone could see it that way. So I’ve moved it after the others. I don’t think it fits well above Admin tabs and there’s already a link to it from the top menu so no need to scroll.

Last edited by zero (2008-08-05 16:40:58)

mrdale · 2008-08-05 17:12:50

Destry> Thanks so much for putting all your time and effort into textbook. I use it a great deal for the tag reference. Thanks is overdue

Zero> You’re putting a great deal of time and effort into the community, Thanks.

Guys> I don’t think anyone is as interested in this drama as you guys. In fact I respect my time more than to read he-said/she-said epistles. Cost to benefit is really low. Fact is you’ll get more work done and it’ll benefit the community more if you can work together. Personally I’m for a cohesive looking integrated reference section for TXP. That means everything looking like it belongs and not like satellite sites on the end of octopus legs. Other communities handle this pretty well, so we can too. That is just my opinion.

hakjoon · 2008-08-05 17:16:25

I don’t really want to get into this whole back and forth but here are a couple of points from my perspective.

Bert’s efforts were not a TxB replacement. They are docs for xPattern. It just happens that right now it’s all pretty similar.

My motivations for looking at dokuwiki before really grounded on update frequency. MW updates way too frequently for my limited schedule to keep up.

While I am happy to keep things running with TxB, my textpattern time has become smaller and smaller lately. I haven’t released a new plugin in forever, and the last update to one of mine was over a year ago, so if someone with more time wants to take over the documentation train I’m ok with that.

Anyway. In the end of the day I don’t care what houses the docs. MW had the advantage of not requiring any transition, but if we are starting fresh…

Textpattern CMS

Textpattern CMS support forum

#16 2008-08-04 12:56:18

Re: [wiki] A New Textbook

#17 2008-08-04 13:09:38

Re: [wiki] A New Textbook

#18 2008-08-04 15:04:53

Re: [wiki] A New Textbook

#19 2008-08-04 16:23:48

Re: [wiki] A New Textbook

#20 2008-08-04 17:20:38

Re: [wiki] A New Textbook

#21 2008-08-04 18:08:55

Re: [wiki] A New Textbook

#22 2008-08-04 18:59:14

Re: [wiki] A New Textbook

#23 2008-08-04 19:26:37

Re: [wiki] A New Textbook

#24 2008-08-04 19:48:48

Re: [wiki] A New Textbook

#25 2008-08-04 20:09:10

Re: [wiki] A New Textbook

#26 2008-08-04 20:09:14

Re: [wiki] A New Textbook

#27 2008-08-05 16:17:20

Re: [wiki] A New Textbook

#28 2008-08-05 16:39:47

Re: [wiki] A New Textbook

#29 2008-08-05 17:12:50

Re: [wiki] A New Textbook

#30 2008-08-05 17:16:25

Re: [wiki] A New Textbook

Board footer