[wiki] textbook architecture

Destry · 2008-09-29 16:14:18

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)

wet · 2008-09-29 16:31:34

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.

ruud · 2008-09-30 13:36:04

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)

Destry · 2008-10-01 08:19:04

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)

els · 2008-10-01 10:54:53

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)

Destry · 2008-10-01 12:45:57

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.

els · 2008-10-01 16:30:18

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 :)

Destry · 2008-10-06 14:49:31

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)

Destry · 2008-10-19 00:44:41

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)

wet · 2008-10-19 04:36:42

Looks rather useless as long as Bert keeps updating PHPXref.com. From a developer’s view, aligning any documentation with the file structure as a primary principle of classification is a rather uncommon approach, and in real life I wouldn’t expect the community to have enough qualified ressources to keep it up to date.

Destry · 2008-10-19 09:55:57

wet wrote:

Looks rather useless as long as Bert keeps updating PHPXref.com.

Agreed, and that phpxref site seems more suited for this kind of info. But what about the Google repo, isn’t that sufficient at providing the same information as far as developers are concerned? Not to mention it’s maintained from the source.

From a developer’s view, aligning any documentation with the file structure as a primary principle of classification is a rather uncommon approach, and in real life I wouldn’t expect the community to have enough qualified ressources to keep it up to date.

Agreed again, on both points.

OK, then. I’ll let it sit for the time being until the Tag pages and other areas in focus are dealt with, but if no good arguments arise by then for keeping those file tree pages, we’ll axe ‘em.

wet · 2008-10-19 10:16:31

Destry wrote:

But what about the Google repo, isn’t that sufficient at providing the same information as far as developers are concerned?

Only partially. “What is used where?” is a question which the repo won’t have answers to, but PHPXref does. This is useful information, and its availability to developers depends on features of their IDEs if it wasn’t available from PHPXref.

hcgtv · 2008-10-19 17:13:38

wet wrote:

Looks rather useless as long as Bert keeps updating PHPXref.com.

The Textpattern Xref gets updated whenever a new stable release comes out, since I run TxP as my main CMS.

When I started PHPXref, I went a bit crazy adding projects. There are many projects that are announced and then later abandoned after only a year of existence, the one year wonders I call them. I’m in the process of identifying which projects are actively developed and I will just concentrate on them. Fewer projects will make it easier for me to keep all the cross references updated whenever a new stable release comes out.

Destry · 2008-10-20 07:13:04

hcgtv wrote:

The Textpattern Xref gets updated whenever a new stable release comes out, since I run TxP as my main CMS.

Good to know, and that confirms removing the pages in question from TxB. I’ve added a link to phpxref from the Extending Textpattern section.

Destry · 2008-10-24 08:44:46

All those file tree pages (all 30+) are now gone. There’s a few more but I’m tracking them. To ensure there’s no heart ache, those pages were last touched in 2006 and there was no content in them outside of file tree navigation lists. I don’t think they’ll be missed.

I also axed all the old tag pages, which have since been recreated under the better titles and presentation in the Tag Reference. More here, if you want to follow-up on that.

I think there will only be one more bulk delete needed, and that has to do with the old translation pages once they are recreated/renamed under the improved convention; i.e., do not have two- or four-character language code prefixes like Zh-tw/txp:if article /. However, I’m beginning to see a potential issue here with regard to the language codes. Consider that tag page just noted, which is a traditional Chinese translation page. Although the page content is fully translated, the title is not, so if we remove the language code prefix and adopt the new titling convention for tag pages, we end up with a page title exactly the same as the English version. I believe this is a problem for any language because tag pages represent code syntax labels so there is no translation of them, right?

If that’s correct, we can solve this problem by putting the language codes as suffixes instead of prefixes (i.e., if_article [zh-tw] and article [fr]) on only those pages that need the distinction between the English mirrors (perhaps just tag pages). Thus, this would not be an automated thing, but an authoring thing at time of page creation. Thoughts on this?

Last edited by Destry (2008-10-24 08:57:20)

Textpattern CMS

Textpattern CMS support forum

#16 2008-09-29 16:14:18

Re: [wiki] textbook architecture

#17 2008-09-29 16:31:34

Re: [wiki] textbook architecture

#18 2008-09-30 13:36:04

Re: [wiki] textbook architecture

#19 2008-10-01 08:19:04

Re: [wiki] textbook architecture

#20 2008-10-01 10:54:53

Re: [wiki] textbook architecture

#21 2008-10-01 12:45:57

Re: [wiki] textbook architecture

#22 2008-10-01 16:30:18

Re: [wiki] textbook architecture

#23 2008-10-06 14:49:31

Re: [wiki] textbook architecture

#24 2008-10-19 00:44:41

Re: [wiki] textbook architecture

#25 2008-10-19 04:36:42

Re: [wiki] textbook architecture

#26 2008-10-19 09:55:57

Re: [wiki] textbook architecture

#27 2008-10-19 10:16:31

Re: [wiki] textbook architecture

#28 2008-10-19 17:13:38

Re: [wiki] textbook architecture

#29 2008-10-20 07:13:04

Re: [wiki] textbook architecture

#30 2008-10-24 08:44:46

Re: [wiki] textbook architecture

Board footer