[wiki] textbook architecture

Destry · 2008-06-28 08:06:20

OK, so there’s two pages in the wiki that are focused on a new IA:

Reorg (has discussion)
Reorg Temp

I’m not sure what the objective difference is. Which one should be focused on?

Second point, we need to breakdown the different aspects of the IA so we see the apples from the oranges. Following are what I believe to be areas of discrete consideration.

Namespaces

Up to now, we have not been using MW namespaces as they should be, or taking advantage of certain ones that could really save a lot of time. Before diving into that notion deeper, let’s remember there are two kinds of content in the wiki: that about using Textpattern (the main wiki topic) and that about the wiki itself. By using namespaces, we keep these two kinds of content separate, or partitioned in ways that make it easier to search, interpret in URLs and so forth.

There are many Namespaces, but here are five to be aware of for the time being: mediawiki:, special:, help:, category:, and template:.

mediawiki: and special: – These are not pages you create, they exist already and largely concern admins. The important point here is that some are very useful and their content can be edited by Sysops to enhance communication/collaboration. That can be explored more later. (help doc)
help: – All wiki help information from this point on will begin with the help: namespace, and be organized in the help:Contents. This includes admin files, wiki how tos, style guide (and related), etc. Any help content existing that is not titled this way will be recreated (not redirected) and the old pages deleted.
category: This, people, is the key to the upper structure and and navigation of the wiki, and what we need to take advantage. Categories are the answer to grouping content by topic, and thus are inherently the tools by which to create the depth, breadth, and primary navigation of the wiki:
- No categories exist by default, you create them as you need them. It’s done easily by adding a category tag to the page you want to group (help doc). When done, an index page for that category is auto-generated having it’s own URL (think of this as a first-level section of a web site). All pages added in similar fashion are automatically listed alphabetically in the category index. Very nice. Thus it’s importort that people create smart page titles that can be alphabetized logically (help doc).
- We’ll recreate pages if needed. Broken links are irrelevant at this point for the sake of improved architecture (as far as I’m concerned).
- Categories can be nested. For example, if you have three categories: Fruit, Berries and Melons, you can nest the latter two into the former to create subcategories, effectively the second-level content structure of a web site. Then, if you have two pages titled Blueberries and Casaba…you get the idea, they are nicely organized in their respective subcategory.
template: – these are like PHP includes (or Txp forms). You create a template of a content chunk that you want output in multiple locations, or can reuse as needed randomly (help doc). These are what we will use for collaboration “flags” that will appear at tops of pages (help doc). These should also be very useful to create mini navigation lists for a suite of related pages. For example, maybe in our Berries category above we have Blueberries, Strawberries, Blackberries and Dingle Berries; we’ll create a mini nav style that can be reused for styling a list that itself can be used for inpage mini navigation. This is easier seen, perhaps, but trust me, it’s killer effective.

Sidebar Structure and Link Options

The sidebar in MW is created dynamically by a series of “portlets.” There are currently four portlets being used, though it looks like more because the second portlet is composed of different lists that a Sysop can edit via a wiki page (mediawiki:sidebar). The first portlet is the localisation portlet (discussed more below.) The last two portlets (“Toolbox” and “Personal Tools”) just appear automatically with no easy way to edit them outside of just hiding the respective options.

To refine the sidebar to something less complicated/congested, we might want to move the Localisation, Toolbox and Personal Tools portlets to different locations so to leave only the Txp topics and wiki help links in the sidebar proper (as a two-list sidebar).

The question is where?

Once we know where, it’s easy to restyle the moved portlets to fit other locations. They do not need to be moved to the same location. For example maybe the localisation portlet is moved to a new right column, or allowed to wrap-out at the top of the page as an inline list. The Toolbox portlet might go to the bottom of the page (as zero has proposed), and the Personal Tools into the header in a more attractive manner than they are in the monobook skin.

Localisation

The way we currently handled localisation is to install a language in the database for each language needed, and then use that language’s namespace (two-letter country code) to mirror the pages (e.g., [[fr:Titre de la page]]. The result of this is another sidebar portlet (the first one) that only appears in context of a give page if that page has another language associated to it.

There’s two aspects to consider here. First is that of moving the portlet as noted above. Second is that the wiki Main Page is used as a “neutral” page…giving equal access to all languages, at least at wiki entry. How might we make better use of the main page and still maintain the localization equality that it has; e.g., fairness/respect to all languages? (Patrick may remember this was a big deal for certain members of the German community when last we considered this issue, so we should not return to those kinds of complications.

Is is time to create multiple wikis…one for each language? (Personally I don’t think that’s warranted at this point for the simple fact of low content volume.)

Last edited by Destry (2008-06-28 18:16:16)

zero · 2008-06-28 10:52:57

Reorg_temp is just there to help me. You can forget about it.

Reorg is now my draft home page IA (apart from wiki, editors stuff which I think should all go in a big footer). Following the main links (ie not the indented ones) leads to secondary pages and I think the navigation namespaces should be based on these sections. As I understand it, categories can be (and should be in this case) used as an additional navigation aid, like with Textpattern.

My aim is to have no more than 3 layers – home page, section pages and individual articles. Home page should be aimed at newbies who don’t know their way around. Therefore, just have links directly to newbie articles on there and links to sections clearly showing what to expect. Hopefully once people have used it a couple of times, navigation should become obvious enought to easily go to the right section page and then the individual article.

So that’s my take on what should be done. You may like to ponder on it… More sections or different names may be needed as I haven’t thought much on that yet. And of course you may have quite different ideas. And there’s the discussion page for Reorg.

Oh, and language (can’t you tell I’m English speaking, leaving this as an afterthought ;) Is the idea to have a different namespace for every language, then a link to each one from the home page?

Destry · 2008-06-28 18:29:11

Finished notes above

zero wrote:

Reorg_temp is just there to help me. You can forget about it.

OK. Thanks.

Following the main links (ie not the indented ones) leads to secondary pages and I think the navigation namespaces should be based on these sections. As I understand it, categories can be (and should be in this case) used as an additional navigation aid, like with Textpattern.

Correct about categories, but see my notes again above about the sidebar “portlets” and then comment again about the sidebar structure. I like the idea of the big footer, as there are various things we can put down there; but as to that other part, are you suggesting the sidebar becomes just a single list with no header? OK, not bad, but what about the localisation portlet? These links need consideration when they appear. Where should they go?

My aim is to have no more than 3 layers – home page, section pages and individual articles.

See my notes about the “neutral” entry point for all languages. This can be a sensitive issue for other lang comms and we are respective of this issue.

What if the home page is just a series of language buttons in a 4-wide grid that just keeps wrapping downwards? Each button is like 40×100px and has either a plain word on it (the language) or is a bit more colorful, like with a flag or national emblem or something. The you click a button and are then taken to the main page for each respective language. That seems like a fair way to go when using a single wiki.

Last edited by Destry (2008-06-28 18:32:22)

zero · 2008-06-28 21:03:05

The problem with having a left sidebar is that it is normally considered to be the main navigation of a site. If Textbook’s primary aim to to help people learn Textpattern, then a left sidebar with editor and wiki information is just plain wrongly placed. Are you saying there has to be a sidebar? I hope not because I consider wiki and editor info to be minor in comparison with the tutorial content and its navigation. If there has to be a left sidebar, then can it be used for content navigation? If it must contain portlets, then I think they should be minimised as much as possible.

The wiki and editor info seems to me to be ideally suited for a big footer with a few columns.

Regarding languages, I think your way is the fair way. The front page used like this could also contain links to the respective forums and perhaps community links? Is there some kind of internationally recognized symbol to indicate language which could be put prominently on other pages to link to the home page – a globe or something?

Destry · 2008-06-28 23:19:36

zero wrote:

…Are you saying there has to be a sidebar?

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.

(I mentioned portlets to explain how the sidebar is composed, but don’t get confused by that.)

… If there has to be a left sidebar, then can it be used for content navigation?

As noted, yes. The sidebar will only be links to the category index pages of the main topic groupings. All content articles in that category will be indexed alphabetically on that page. As well, there will be subcategory links on the index pages that enable users to filter content by a second-level category, and so forth as deep as you want, though I don’t think you’ll need to go deeper than a second-level category, especially since there’s not that much docs anyway.

If it must contain portlets, then I think they should be minimised as much as possible.

Again, there should be a minimal sidebar, which means there will be one portlet that provides the category links I just described, and which can be edited via mediawiki:sidebar page by Sysops. The other links can go to the bigfoot columns, though we still haven’t decided upon what do to with the language “mirror” page links that can show up from page to page. I’ll think on that.

Regarding languages, I think your way is the fair way. The front page used like this could also contain links to the respective forums and perhaps community links?

Those links you suggest are a nice idea, but I think they would belong on the actual index page respective to each language. All we’ll see in the home page main content area are the language buttons to their respective index pages, nice and clean (and of course the masthead, sidebar and footer).

Is there some kind of internationally recognized symbol to indicate language which could be put prominently on other pages to link to the home page – a globe or something?

I would say it depends on the globe. A typical earth globe with green land and blue seas…no! For one thing it’s often used to symbolize ‘websites.” For another it’s already used in the editor mode for the external link button. On the other hand, a globe that is nothing but lat/long lines could be possible. That would be different enough and perhaps still suggest “localization.”

However, there only needs to be one link to the main page (besides the wiki logo), and that should be either the top or the bottom link in the sidebar, since the sidebar will always appear on every page in the wiki.

——————

I think I have a pretty good vision now of the home page layout (no fancy stuff yet) and can come up with a decent mockup for improved discussion. First, however, I want to get the dev spot set up and the file structure in place. All I need is either a dump of the wiki db, or credentials to the server so I can get it myself. I’ll need the latter anyway so I might as well get that from someone…Patrick, wet, ruud?

Another note: I’ll be on vacation the first three weeks in July, likely offline. Upon return I’ll be thrown into moving and having my online service interrupted for an as of yet undetermined period of time…hopefully not much. -Anyone know roughly when 4.0.7 is expected? That would be the latest time period for which I would like to see the new wiki done-~See below.~.

EDIT: A note about wiki catagories…we should use them when it’s appropriate (which is generally when you have collected a reasonable number of content articles to go into a category, and thus worth alphabetizing the articles); however, if a given topic category only has a few articles, then it’s admittedly better to have a regular wiki page serving as the topic index. Over time, as the page grows, it can be converted to a category index and all the contained pages categorized…a few minutes work at the most.

Last edited by Destry (2008-06-29 09:12:36)

wet · 2008-06-29 08:25:07

Destry wrote:

All I need is either a dump of the wiki db, or credentials to the server so I can get it myself. I’ll need the latter anyway so I might as well get that from someone…Patrick, wet, ruud?

Nope.

Anyone know roughly when 4.0.7 is expected?

Roughly: Not in July, but later. More precision would overtax us at this moment.

Destry · 2008-06-29 09:00:29

“Nope” you won’t give it to me or “Nope” you don’t have the login details? No matter, I don’t need the dump file anyway. I’ll install a clean MW, copy a few pages over for context and reskin. As long as TxB is current with the latest version there should be no problem merging the new skin when the time comes. This means all info restructuring under the Main Page should happen live in the existing site. The sooner the better.

“Roughly” is all I need. Maybe more important to know than when 4.0.7 is roughly out is when the new .com design is roughly ready so the wiki and .com can relaunch at the same time.

Last edited by Destry (2008-06-29 09:01:27)

zero · 2008-06-29 10:04:41

Destry wrote:

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.

So there doesn’t have to be a left sidebar! So the content can go in its rightful place – near the beginning of the source and not surrounded on all sides by other things. Great!

To me it is not logical to have a left sidebar and I didn’t say it should be simplified to main categories – I only said that scenario would be better if there had to be a sidebar, but there doesn’t. If there must be one, and I’m not sure it is logical yet, then I would argue it is better on the right – like the mozilla wiki

I need to understand what you mean by categories. You say above:

category: This, people, is the key to the upper structure and and navigation of the wiki, and what we need to take advantage. Categories are the answer to grouping content by topic, and thus are inherently the tools by which to create the depth, breadth, and primary navigation of the wiki

So, let’s take Textpattern 101 as an example. In that article there are lots of topics written about, so should categories be: installation, interface, how it works, how to use it or perhaps pages, forms, styles, sections or perhaps tutorial? How would you categorise it?

If you say categories are going to be the main navigation, then I would have a Getting Started category and put it in there. Is that what you mean too? I am confused because Getting Started in not a topic but a division by level of difficulty and I would call it a Section, whilst reserving categories for secondary navigation based on topic. I wouldn’t want topic categories cluttering up the place – there could easily be 100 of them – but prefer them in a drop-down list.

The sidebar will only be links to the category index pages of the main topic groupings. All content articles in that category will be indexed alphabetically on that page. As well, there will be subcategory links on the index pages that enable users to filter content by a second-level category, and so forth as deep as you want, though I don’t think you’ll need to go deeper than a second-level category, especially since there’s not that much docs anyway.

So perhaps sidebar category: Getting Started. Category page sub-categories: installation, admin, presentation, content. Is that what you were thinking?

What about the nav at the top of each article – the one just below the title? Sometimes it is a breadcrumb, sometimes a list of sections, sometimes not there at all. Is this generated automatically? It seems a good form of navigation and means we could dispense with the sidebar. Or were you thinking of dispensing with the top nav and using a sidebar instead?

My main concern causing me to ask all these questions is that the actual content users are wanting to read is always in danger of getting buried among wiki stuff and the wiki stuff is too much of a distraction from reading the Textbook. Perhaps it’s because at the moment it surrounds it on all sides. Ideally, imho, it would just be top breadcrumb and big bottom footer. The Article Discussion Edit History Move Watch links could be moved to the footer, as can the external links to txp, resources etc.

I’m not fixed in my opinions on the best way to organise the information but am sure that the content must be given far more priority. That includes future Textbook articles which need to be written for the web rather than being written as if they were a book. Not many people will wade through beautifully-written introductions, sidepieces, anecdotes etc to discover what a form is.

zero · 2008-06-29 11:23:10

Re Language: there are many arguments against using a flag, eg this one by Jukka Korpela

There’s an article here with many interesting comments including this one

I searched Google for ‘international language symbol’ and ‘icon for international language’ and other things but can’t find anything with my search terms so far. I think the globe in all its forms is probably overused to mean many things. But how about 3 small identical ‘faces’ – with just the colour of white, yellow/brown and black to distinguish them? The faces would take you to the opening portal page and the Textbook logo would take you to the language home/index page. If the portal page only has text links as suggested in the articles above, it leaves plenty of scope to make it a beautiful unique page to give a warm welcoming feel. It could perhaps be a standalone htm page so it is not loaded down with lots of gubbins in the source. Just my 2p…

Destry · 2008-06-29 12:38:32

zero wrote:

I need to understand what you mean by categories

Based on some of your statements, which reveal your general knowledge of MW, I’d say you need to understand more than just categories.

Tip: Don’t get confused by Txp terminology and MW terminology having the same terms. They don’t match up.

Categories

Read this from the source and you should understand categories.

Basically, a MW “category” can be a topic category (I gave the example of Fruit already), or a — using your words — “division” category. To MW they’re the same thing; it’s simply a way of partitioning content by related subject matter.

Note my “EDIT” at bottom from earlier today that suggests when a regular wiki page would be better instead.

What about the nav at the top of each article – the one just below the title? Sometimes it is a breadcrumb, sometimes a list of sections, sometimes not there at all. Is this generated automatically? It seems a good form of navigation and means we could dispense with the sidebar.

Let’s stick with proper wiki terminology so you are enlightened and I know what it is you actually mean without rereading. The different “nav” you’re talking about:

Table of Contents – This is the “list of sections” you refered to.
Templates – These create the other things you mention, and I already mentioned these in an earlier post. They are extremely useful. Work like Txp forms and can insert content anywhere you want: top, bottom, left, right, middle, inline, whatever.

My main concern … is that the actual content users are wanting to read is always in danger of getting buried among wiki stuff and the wiki stuff is too much of a distraction from reading the Textbook.

Unwarranted.

Perhaps it’s because at the moment it surrounds it on all sides.

Exaggeration.

Ideally, imho, it would just be top breadcrumb and big bottom footer. The Article Discussion Edit History Move Watch links could be moved to the footer, as can the external links to txp, resources etc.

Sure, we can move things around, or hide what we really don’t need, but remember, this is a wiki; it’s going to have wiki functions for people to use. People are not only going to be reading the wiki, they are, hopefully, going to be contributing to the wiki too, and just like they don’t want to have to hunt hard to find content, they don’t want to hunt hard to find the tools they need either. Throwing everything into a big, footer at the bottom of the page is not one of the soundest UI principles going, and that’s not just my opinion.

I’m not fixed in my opinions on the best way to organise the information but am sure that the content must be given far more priority.

We can (and will), improve the existing UI, but we will find a balance between reading the wiki and using the wiki.

That includes future Textbook articles which need to be written for the web rather than being written as if they were a book. Not many people will wade through beautifully-written introductions, sidepieces, anecdotes etc to discover what a form is.

No disagreement here, but this has nothing to do with wiki functions, but rather everything to do with better authoring and editing of the content. If you really want to be productive, get in there and get busy editing and organizing instead of debating it here!

Closing Comments for All Readers

I don’t want to discuss everything ad nauseam, including the use of icons, which are irrelevant if they don’t work with the .com theme anyway.
I’m going on vacation, then moving, and don’t have a lot of time (practically nil) between now and mid August.
I will now turn my attention to a dev location for the skin, where I’ll be skipping the mockups for live prototyping.
I’ll invite a few people to have a look when the time comes (those I’ve already mentioned elsewhere, and a few more to be quietly determined), give feedback, and make adjustments accordingly.
That will be the end of the skin redesign as time will already be an issue, I’m sure.

I consider Patrick (hakjoon) the TxB “leader” and if he wants to give final word on anything…ANYTHING…he only has to speak up.

I’ll also repeat what I mentioned elsewhere: that is if ya’ll want to use a different system, say so and I’ll bow out. Easy as 1-2-3! It might even be interesting if someone went ahead with a Docuwiki side project, or whatever, for a comparison down the road. Have at it.

hcgtv · 2008-06-29 14:32:29

Destry wrote:

It might even be interesting if someone went ahead with a Docuwiki side project, or whatever, for a comparison down the road.

I am.

Destry · 2008-06-30 00:04:32

Excellent! Quiet initiative. I like it.

If you have it all done before mid-August, that might be the bend in the road. Meanwhile, elves will work.

Textpattern CMS

Textpattern CMS support forum

#1 2008-06-28 08:06:20