Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Re: [wiki] textbook architecture
In response to the questions posed here
zero wrote:
So you include namespaces with content?
Curious question, I wonder where it’s going…
I speak for namespaces as they exist in MW. Namespaces themselves are not content, no, but they do partition content, make it easier to search content at the namespace level, and in some cases serve as the means to output content (like category: and template:). I talked about some of the key MW default namespaces in this threads head post. Some are strictly MW system use, others are what authors will generate if needed (e.g., category:, template:, help:). What I was trying to say before is that wiki projects often don’t use namespaces effectively (generally from a lack of knowing about them) and thus don’t benefit from what they can offer. This was true for TextBook in the beginning; it was new to a lot of people, including me. I’ve learned quite a bit since then about MW and would like to roll that knowledge back into TxB this time around.
The only namespace we should need to be concerned with initially is category:, as this is the one that can be effectively used to mimic the concept of site sections (top-level organization). Here’s a couple good tips for using categories:
- Categories in MW are easy to create, delete and rename, as well as move pages from one category to another, so it’s not critical to name categories perfectly from the start. The only concern is that a category index page is itself a unique URL so there’s the issue of breaking those links over time. In my opinion, that’s less important than making the wiki more usable. If a wiki is more usable, readers will readjust easy enough and probably be glad for it. In complete overhauls like we are doing, it’s warranted anyway.
- Don’t immediately start with using a category if a simple wiki page serving as a list of deeper topic links will do. As the page links grow in number and are fit to be subcategorized, then you can introduce the category(ies) easy enough. A category index with less than 10 pages is not really a good use of a category. A simple page with a bulleted list of article titles will do. (Build up to categories, don’t create voids unnecessarily.)
- Create category names that are indicative to the topics pages they suggest, but are concise as possible (not more than 3 words is best). The first helps ensure readers will understand them, naturally, but also helps prevent having to use wiki link syntax tricks to alias category link labels that may not have been thought out well to begin with. The latter point simply makes it easer to type the category tag when used to add a page to a category (done by adding the category tag to the bottom of the given page).
The important thing to note about namespaces at the moment is that we will never need any custom namespaces if all we are talking about is Textpattern documentation. All those pages will reside in the main: namespace (the default). We might only ever need a custom namespace when there’s a workgroup project taking place in the wiki for something other than Txp documentation (these initiatives used to exist). We would then give that workgroup a namespace and effectively keep those pages separate from the main: namespace so not to clog up the primary docs.
By the way, all custom help documentation we create (i.e., wiki help or admin docs) will begin with the help: namespace. Existing help pages that don’t have this will be changed. Again, this keeps these pages out of the main docs namespace as desired.
zero wrote:
[I]sn’t the skin the last thing on the agenda? What about IA and the top-level organizational factors you have in mind? Surely they don’t include “thinking deeply into the words on each wiki page at this point” so can you share a paragraph about those with us?
Information architecture (IA) is a very important factor indeed in determining the direction of of any web site, but we don’t need to be overzealous here. There’s a couple of big differences between a wiki versus any other kind of project (unless a wiki is a component of a more holistic project, but that’s for TeamTextpattern to decide). First, the “information” with regard to a wiki is simply text content served up at the page (article) level, whereas for other projects you might have to consider server farms, discrete systems, multiple applications, interactive forms, associated workflows, and on and on. There’s workflows and forms in the wiki, of course, but they are already established and nothing we need to mess with. Second, wikis are inherent of change over time. That’s the whole point of a wiki and you don’t want to prevent that from happening by an overly rigid or granular IA. Other projects, such as those driven by CMS planning, are considerably more finite in aim, and thus might spend more time in the beginning mapping it all through a series of phases including IT audits, site structures, functional assessments, storyboards, graphic charter, et cetera).
Clearly we don’t need to do all that with TextBook, and again, it’s a wiki so we shouldn’t do it either or we restrict content evolution. All we need to know is how to organize the content better at the top level, and fit that into the existing navigation tools the wiki provides. We can than create/delete pages and copy/paste text as needed and to our hearts content. Where we need more navigational control (like all wikis do), we develop it ourselves in the wiki using conventional standards and wiki tools like templates (create once, use multiple places). Relatively easy stuff.
So if I seem to have de-emphasized the need for IA work, I have and I haven’t. :) In other words, it’s good to know what your aiming for but we don’t need to waste time being overly analytical, it’s misplaced on a wiki. You know the old adage, “a picture is worth a thousand words,” or something like that. Well that may not be relevant for the guys at 37Signals, but in this case I think that’s accurate. Before I do any actual skinning, I’ll do a mockup or two in Fireworks that gets the points across visually. It will then be easy for folks to see and comment to four things:
- Relatedness with the other sites (e.g. textpattern.com)
- Top-level organization (by way of navigation vectors)
- Intuitiveness of semantics (e.g., nav link text, headers…)
- layout and presentation
Offline
Re: [wiki] textbook architecture
One thing I personally need some feedback on is how to handle the main page with respect to the language efforts. Currently TxB is called TextBook International and the main page serves as a language panel of sorts for getting into the language pages of one’s choice.
Do we stick with that idea, or do we return to the idea that the wiki is English by default and all localization pages are simply mirrors from whatever given page a reader is on. So in this case the main page would be more like an English index of TextBook with the localization links at the side.
I’m sensitive to all our translators and their contributions over the years have been great. I only wish there was more input from them in matters like we have here now.
Feelings?
Offline
Re: [wiki] textbook architecture
Thanks for answering my questions, Destry. They weren’t the answers I wanted or expected but they certainly give food for thought! In answering them you have also answered my previous questions in this thread, so thanks for that too. It’s a strange concept (to me) that the MW namespaces are fixed-ish and there’s no need to suss them from the very start, but can adapt as you go along, but MW seems very complex compared with Dokuwiki and that puts me off because I’m a simple soul approaching this thing in a simple manner, hopefully not simplistic, but we’ll see! The way you write about it with all the lists and analysis, anyone would probably think Textbook is a very complex project, whereas I see it the same as a web design with a few extra admin things to sort out. So I guess our approaches are so dissimilar and MW and DW are also dissimilar (namespaces quite different), that it was inevitable that we would clash.
Re language and the front page, whatever you do make sure someone who speaks or reads no English can clearly see what they should click to go further. I moved the language part to the bottom for a while until I realised a non-English speaker would probably not find it and go away very fast. I like the way the Dokuwiki language plugin does the job over here. I was planning on using the main page just for language links and language related articles, as it seems fair all round. But the plugin makes it fair too, and intuitive, but it seems like there will be another way with MW.
Offline
Re: [wiki] textbook architecture
Seeking feedback on these motions for IA modification in TextBook. They are significant changes that impact other smaller changes so I want to run it by folks before just doing it:
1) Adopting the term “Back-office” to refer to the login side of Textpattern.
There is no consistent way of saying the login side of Txp. There’s a lot of variation around “Administration” like “back-end administration,” the “administration side”, etc. but nothing consistent or dicisively clear for the sake of documentation. Further, “Admin” is itself a back-office panel talked about in documentation. This is where certain set of tasks are done by the site admin; however, there could be site authors accessing the back-office that have nothing to do with site administration so it doesn’t make sense to write docs in context for these different back-office users when only one type is actually “admin-ing” per se. Back-end is another term often used, but I think this is a mis-use. Back-end, is probably more indicative of the server tree and database, not the web interface of the back-office. Finally, “back-office” is not something I just made up, it’s used prominantly around my region to indicate exactly the same thing. (In contrast, “front-office” is used to refer to the public user side.)
Other point of this is to rename back-office pages so they reflect only the tab label (e.g., “Admin”, “Content”, “Presentation” etc.) This will make it much easier to link to these locations in context without having to use extra wiki link syntax to change the link lables.
You can see an example of what I’m getting at here, where “Back-office” in the left would take you into the back-office docs. Only a few pages given to show the idea. Note the effective use of the mininav for aiding navigation within scope of the back-office pages.
2) Re-architecting the Tags Reference as it exists but using wiki functionality to lower the maintenance and improve navigation.
This does not imply the actual page content. That’s a different focus, and zero may already have given initial attention to content. I’m suggesting changes to the organization of the pages in context to MW abilities so it’s easier to maintain and navigate.
Suggesting three changes here:
- Using categories to regroup pages alphabetically, but automatically (no more long alphabetical list is needed). This is probably the only location in TextBook that could really benefit from MW categories.
- Using a mininav template (use once in multiple places) for the horizontal hops between tag group types; e.g., Page Tags, Form Tags, etc.. (By the way, tag group pages in the wiki were a carry-over from Pedro’s original tags reference, but if they are considered irrelevant/confusing, then now would be the time to drop them. Feelings?)
- Rename tag pages to be less syntaxy and more human readable.
I’ve made a configuration change in the demo so that page titles are no longer case-insensitive. If you type lowercase, it’s treated and appears as lowercase. This makes it effective to user lowercase for tag page titles so they are distinctive enough from pages having similar names; for example Articles (the “Articles” tab in back-office) and article (the article tag). Underscores can also be used for compound tag names (e.g., “article_custom”), but the underscores do not show up in the page titles themselves, but they will in the in-line links.
3) Dropping the Glossary
The glossary has very questionable value (who maintains, and dare I say, even reads the glossary anyway?). We could easily argue that it’s contained definitions are better addressed by other pages that focus on the very topics. Further, it’s poorly constructed as a long page with other pages linking to it’s various sections. Finally, the glossary will conflict with the changes suggested above because of the tendancy to link to the glossary using similar link labels. If we drop the glossary, we have no conflict and it’s one less mess in the wiki to have to maintain.
Last edited by Destry (2008-09-29 16:16:33)
Offline
Re: [wiki] textbook architecture
Destry wrote:
Page Tags, Form Tags, etc.. (By the way, tag group pages in the wiki were a carry-over from Pedro’s original tags reference, but if they are considered irrelevant/confusing, then now would be the time to drop them. Feelings?)
I expect significant growth in polymorphic tags, for instance <txp:category /> would have different semantics in a page, an article or a category list context in 4.0.7. I think this information bit should not go into explicit (high level) Tag Groups in the future but into a multiple-choice list at the individual tag reference page.
Offline
Re: [wiki] textbook architecture
Back-office => admin-side (as in admin-side vs. public-side)
tag group pages in the wiki were a carry-over from Pedro’s original tags reference, but if they are considered irrelevant/confusing, then now would be the time to drop them. Feelings?
Yes, drop them. Instead I’d go for one page that groups the tags by function and at the same time makes clear in which context the tags can be used. Something like this
As Robert already mentioned, some tags can be used in different contexts. Those tags could show up multiple times in such a listing.
Rename tag pages to be less syntaxy and more human readable.
Do you mean calling them “article_custom” instead of “txp:article_custom”?
The Glossary page content can probably be moved to other pages. For example I see a lot of tag syntax related content. That should probably go to a page that gives detailed info on how tags work. The only really interesting thing I found was how to correctly spell Textpattern and Txp ;)
Last edited by ruud (2008-09-30 13:40:55)
Offline
Re: [wiki] textbook architecture
ruud wrote:
Back-office => admin-side (as in admin-side vs. public-side)
OK.
Yes, drop them. Instead I’d go for one page that groups the tags by function and at the same time makes clear in which context the tags can be used. Something like this As Robert already mentioned, some tags can be used in different contexts. Those tags could show up multiple times in such a listing.
OK. I like that idea. I may not be the best person to arrange that page (tags by function), but I’ll start the page and others can help structure it.
Do you mean calling them “article_custom” instead of “txp:article_custom”?
Yes, because if every tag page begins with “txp:” the wiki will alphabetize everything under “t” (the first letter of the page title). That clearly wouldn’t work and thus we would not be able to take advantage of the auto-alphabetizing function of the Tags category. I don’t think this will be confusing in the wiki; once all pages are alphabetized that way it will be obvious they are tag pages. Also, we can slightly change the structure of the pages so when you go to a tag page, say article_custom, the full tag syntax is immediately under the title, followed by the short description, and then the examples (etc.) which the wiki creates an in-page TOC for.
Ed. It should be noted the “Textpattern Plugins” site (example”) and the FAQs (example) refer to tags this way as well so such a change in TextBook would be a strong move to standardizing how tags are documented across the board.
Another thing I want to do (later) is implement the PDF generator for multiple pages so it’s possible to download the full set of tag pages as a single pdf file. It needs confirmed, but I’m guessing the more pages align with how MW is designed to function (in other words, pages alphabetized by MW category), the better that extension will work.
The Glossary page content can probably be moved to other pages. For example I see a lot of tag syntax related content. That should probably go to a page that gives detailed info on how tags work.
Certainly, all salvageable content will be re-cycled.
The only really interesting thing I found was how to correctly spell Textpattern and Txp ;)
Oddly enough, there was a lot of confusion about that 3 years ago or so. TextBook’s spelling probably didn’t help any, and the fact you see that in the glossary is an good example of how little the glossary is even looked at.
Last edited by Destry (2008-10-01 09:23:43)
Offline
#20 2008-10-01 10:54:53
- els
- Moderator
- From: The Netherlands
- Registered: 2004-06-06
- Posts: 7,458
Re: [wiki] textbook architecture
Do you mean calling them “article_custom” instead of “txp:article_custom”?
Yes, because if every tag page begins with “txp:” the wiki will alphabetize everything under “t” (the first letter of the page title). That clearly wouldn’t work and thus we would not be able to take advantage of the auto-alphabetizing function of the Tags category. I don’t think this will be confusing in the wiki; once all pages are alphabetized that way it will be obvious they are tag pages. Also, we can slightly change the structure of the pages so when you go to a tag page, say article_custom, the full tag syntax is immediately under the title, followed by the short description, and then the examples (etc.) which the wiki creates an in-page TOC for.
One quick observation: what about the page title? At the moment for the txp:article tag it’s ‘Txp:article / – Textbook International’. I understand the advantages of removing ‘txp’, but would it be possible to add ‘tag’ or something to the page title? I’m thinking of the situation where you have multiple tabs/windows open. It doesn’t go for all tags, but ‘Article – Textbook International’ is not as obvious as ‘Txp:article’ or ‘Tag: article’.
Another thing I want to do (later) is implement the PDF generator for multiple pages so it’s possible to download the full set of tag pages as a single pdf file.
I’m sure a lot of users would welcome that!
Last edited by els (2008-10-01 10:55:47)
Offline
Re: [wiki] textbook architecture
Els wrote:
I understand the advantages of removing ‘txp’, but would it be possible to add ‘tag’ or something to the page title? I’m thinking of the situation where you have multiple tabs/windows open. It doesn’t go for all tags, but ‘Article – Textbook International’ is not as obvious as ‘Txp:article’ or ‘Tag: article’.
Making tag page titles in lowercase (and those pages only) was the reason for this kind of thing, to help make the immediate distinction.
However, we could append “Tag” (probably the best alternative) to each page title (e.g., article_custom Tag) if people would rather do it that way (and I would say that “Tag” is capitalized to distinguish it from the actual tag name, which is proper convention), but here are the cons to be aware of:
- It’s not as clean (obviously)
- It’s somewhat reinventing the same situation I’m proposing to eliminate with the “admin-side” pages, which is to say drop the “Subtab” from the page titles and simply call the page by it’s tab name (e.g., “Diagnostics” instead of “Diagnostics Subtab”). Same logic could be said for tag pages.
- Somewhat related to #2, adding “Tag” will likely increase the need for authors to create a lot of alternate link labels when refering to pages in inline copy.
We should consider wiki authors as much as wiki readers. In that respect, which wiki link option below is both easier to type and visually more appealing?
- [[article_custom Tag]] —> article_custom Tag (more to type and not a pretty link)
- [[article_custom Tag|article_custom]] tag —> article_custom tag (lots more to type to get the pretty link)
- [[article_custom]] tag —> article_custom tag (clean typing and the pretty link too)
To my mind, #3 is the right choice. At any rate, that’s the perspective, just let me know for sure which way folks would rather do it, and we’ll do it.
Offline
#22 2008-10-01 16:30:18
- els
- Moderator
- From: The Netherlands
- Registered: 2004-06-06
- Posts: 7,458
Re: [wiki] textbook architecture
Hi Destry, thanks for clarifying. I hadn’t considered the cons, just looked at it from a user’s point of view. So of course I agree with your choice :)
Offline
Re: [wiki] textbook architecture
I’ve made some headway on the basic top-level organization, but there’s a fair bit to do and refine yet (Tags category being just one facet). I won’t be able to mess with again until tonight or tomorrow. If people understand the idea behind the tag pages, they could certainly go ahead and start recreating those under the Tags category.
I’m not sure “moving” pages to the lowercase titles will work, but I would advise against that anyway as the wiki will just be full of redirects, and too many of those is just as confusing to navigate as otherwise. Instead I would propose creating new pages with the new name and let the Reference reinvent itself naturally.
Ed. Please take all Tags Reference related discussion to that topic. Thanks.
Last edited by Destry (2008-10-07 10:16:43)
Offline
Re: [wiki] textbook architecture
I’ve come across a whole bunch of pages that all stem from TXP Directory and File Structure
I know these can be handled better using templates and categories, rather than a bunch of redundant lists, but my first questions are is this really an attempt to document the file tree? Is that practical? Is it really beneficial against the overhead involved?
I would also argue this is not really end-user documentation, but rather developer interest. Thus if these pages are even valued for keeping, they should be organized into a category:File Tree (and relevant subcategories, most likely), as well be put into a custom namespace that takes them out of the main user-docs namespace.
Note many of these pages (crazy titles) started with lowercase, which have since been forced to upper case due to the recent no-caps config, so there’s a LOT of page renaming just right there.
Bottom line: If we keep these there’s a ton of work to do; however, if they are not really beneficial then maybe we just delete them?
Thoughts on this issue?
Last edited by Destry (2008-10-24 07:49:21)
Offline