[wiki] Wiki homepage content

jsoo · 2010-12-15 03:06:36

Destry, I support pretty much all the suggested changes you’ve put forth from the start of this thread. I still think a user should be able to take in the entire homepage at a glance. The link you provide perhaps supports this with another point further down:

Could this element be placed on a secondary page will equal success?

I think the current homepage tries to be too comprehensive, apparently in an effort to provide most all of the links a user is likely to need. It falls between being a complete index and a focused portal into the rest of the site, failing at both.

Destry · 2011-07-22 15:20:15

Some thoughts I was playing around with…

Main content area…

Some things to note about what’s suggested in the image above.

But first, blurbs under each section are not final. I don’t think they’re bad, but I see where a couple of things could be changed already, so let’s not get hung up on that right now. Do, however, comment about the nature of the sections themselves. Mer-sea.

Installation
This is a considerable paring down. I think we have way too many docs covering different kinds of installation. It’s not – that – complicated. Two docs is all we need: a simple .zip install, and something for the command-line jocks. All those other pages are just pointless and make Txp look more difficult than it is. (I’m mostly to blame; just admitting it’s time for a diet.)

Administration
You might notice the curious links here. One thing that’s bothered me about the the admin-side docs currently, is the lack of context to a site building workflow. As it is now the pages just describe what’s on each panel, or go into more detail than necessary in some cases. We’ll keep those pages. They’re good. But there could be something more contextual that helps people, and that’s what those links start to suggest there. Each would be a page (or maybe sections on a single page) that introduces the different admin-side panels as they come into play with actually constructing a site (more or less; we shoot for the most trodden path). The pages (or page) would reference the other (existing) associated panel pages in context. This basically provides a storyline, if you will; giving new users something to parallel on on they walk through it.

Tag Reference
No change

Top 10 Tutorials
The idea here is to provide 10 high-qualitiy tutorials that focus on what Txp users most want/need to do when they start out, based on historical observation. I’m willing to take on much of that writing, but I need everyone’s help with figuring out what the 10 most desired tasks are.

Themes
This is a new section that will provide new content focusing on the default theme construction, and how to create new themes from scratch according to recommended methods and plugins, etc.

Extension
Pretty obvious.

A (hard-to-see) mockup of the greater page. Still missing some design elements, but you get the idea…

The design of the home page would be structured with a table (no, it doesn’t matter), and the content would be inserted via wiki templates. That way the page could be locked to guard the presentation while people could still edit the content via the templates, which is how it should be for complex layouts like this anyway.

Last edited by Destry (2011-07-22 18:54:51)

Destry · 2011-07-23 08:54:28

Destry wrote:

The design of the home page would be structured with a table (no, it doesn’t matter), and the content would be inserted via wiki templates.

What was I thinking (rhetorical)… I played around a bit with this last night and my brain just does not work in tables nested 3 deep (a la Google Sites); divs will be far easier, and their practically already their. Making them lineup (like rows rather than masonry) is still possible with a fraction of the ugly code. Wiki templates will still be the norm for editing content…not editing the homepage itself.

Carry on.

Bloke · 2011-07-24 20:54:12

I really like that direction in your screenshot. The paring down of content, and also making it contextual will be a big boon to the community. There’s just too much junk in the wiki so this effort combined with the style guide(s) (the one about best practice for writing themes and plugins — DOM/CSS hooks, etc — is one I was supposed to write ages ago) will make a huge step change in usability for everyone.

Let me know what I can do and which buttons to press.

Destry · 2011-07-24 21:25:42

Thanks, Bloke.

The home page can be changed just about any time, but we should have something behind those topic sections so they actually mean anything beyond just placeholders (with exception to the 10 tutorials, which could be replaced with something else).

Specifically, we need something under the the Themes and Extension sections. It doesn’t have to be finished docs, but it should be at least something useable, even if work in progress.

I’d suggest we first make two new threads in the user doc forum here, one for each—Themes docs and Extension Docs—that starts a list of existing and/or needed doc pages for each one (and ensuing discussion). These could be our drafts of the eventual index pages, respectively, for each topic. If docs exist in the wiki or elsewhere already, then add the links on those items so we can find them easier.

Last edited by Destry (2011-07-24 21:27:19)

Destry · 2011-08-04 13:03:54

In case anybody blinked, I’ve reconstructed the docs home page as conceived in the concepts above. The new topic blocks should be fairly clear with their intention, and in some cases initiate new content objectives.

It would be great if we could get in the habit of using the wiki discussion pages when talking about a given wiki page, though you might have to indicate here you’ve done so to give people a heads up to “Watch” those pages for further notifications.

I’d like to just quickly touch upon the left navigation and it relates to a few things…

Orientation

I think it’s time we can do away with this page, and thus the link in the left nav. There is nothing on that page that can’t be better indicated in context to other documentation topics (the semantics stuff), or which does’t really belong anyway because of the type of information it is. Licensing doesn’t help a person use Txp. And features is just marketing babble. Etc. All that belongs at .com where it’s already at.

Installation

As already mentioned, the aim here is to focus on two primary documents (.zip install and command-line/subversion install), and get rid of all the other pet documents about operating systems, hosts, etc which are never kept up to date anyway.

For the moment, those old pages are there (and unsupported), but they will be scanned for anything worth keeping and then trashed. When that’s done, the “Installation” link in the left navigation will point to the template:Installation file that feeds the home page block.

If anyone wants to take those old install articles for OS types or specific hosts and turn them into personal blog posts to maintain at your own site, you’re welcome to do so before they’re canned.

Last night I wrote the new .zip install doc. It combines the simple install, detailed process, and simple updgrade all in one page. It’s also more concise and without use of images, which were missing, and which I think were irrelevant anyway. I think you’ll find this document is organized and usable, and includes a contextual link to the system requirements right at the top (speaking of contextual writing).

The new command-line doc needs written and somebody who operates that way (and under versioning) could start fleshing it out. I’ll be happy to clean it up as it goes.

I have one question: what is the official Txp project code repo now…google code or github (they both seem to be current)?

Administration

This link now points to the template providing access to both sets of admin-side documentation; the one that exists, and the one that will be written in workflow context. The link label has been changed to accommodate both sets, rather than just the organizational docs.

Tag Basics

This is already available from the Tag Reference index. I don’t think it needs to be a navigation item. It’s second level to Tags.

Extending

I want to change the label here to Extension (a verb form more consistent with Installation, Administration), and I’d like to rename the destination page to Textpattern plugin development, which is a bit more clear in meaning. Anybody have a problem with that?

Troubleshooting

I have no problem with this nav item, but I don’t think the index should be a category page. We’re never going to have enough troubleshooting docs to need to alphabetize them (I sure the hell hope we don’t need a lot of troubleshooting documents), and thus a single page that details the current troubleshoot issues should suffice. It’s much easier that way to see where troubleshoot answers could be written into context in other locations too (or instead).

FAQs

Bringing your attention to the new FAQ block. This will become a nav item, and it will be a single page for the 10 most frequently asked questions. Textpattern.com’s current list of over 100 FAQ is ridiculous, and no doubt a bugger to maintain. Seriously, if you’ve got more than 25 (most) FAQs, you’re not helping people who would otherwise use them. You’re mixing the mud puddle.

I have an FAQ audit in process. It’s a spreadsheet that lists out all the .com FAQs (the listing out part is what needs done first and I thank Els for a big hand with that), and includes columns to evaluate the status of each one. It considers things like: Is the content already in the user docs, and if so where? If not, is it something that could be easily written into the docs in context to a relevant topic and/or location (e.g., admin-side related). That sort of thing.

When the audit is done, I’ll make the completed grid public, which should help people with documentation efforts. When all said and done, we should be able to fortify the user docs with FAQ knowledge, thereby whittling down the FAQ numbers to 10 (target) or 20 max to be used in the new FAQ block. This also has the benefit of moving the FAQ knowledge (written in context to topics) to where it will be more usable and easier to maintain, and .com can simplify it’s web content, which is unlikely to get much grooming anyway.

Deletions

This is not a section, but means to inform people of what is going to happen to deprecated wiki content. We’re not keeping old pages in the wiki for a rainy day that will never come. When content is improved upon, the old ROT is removed so it doesn’t clog up the pipes and confuse the masses.

If we have to start keeping a robots.txt file to redirect stuff, so be it, but I’m aiming for a docs architecture that is purposeful and concise, not confusing, confounding, or clusterfucking.

MixedContent · 2012-02-26 03:03:07

I like the look of the default/default/default page that comes with the Textpattern installation. And given my intentions for the web site I’m trying to re-implement, I of course want to change that default content. And the default layout. And the default organization.

Specifically, I am not implementing a blog-type site. Articles are not to be signed, and their publication date is of no importance. I have forty-some pages to add to the site, each of which contains from one to five separate chunks of text, plus some header, footer, and navbar stuff.

I have been having some difficulty understanding how to accomplish this, possibly because the naming conventions of Textpattern (Sections, Pages, Forms) are a bit out of alignment with common use. I suspect it’s extremely simple if you understand the way the elements of Texpattern fit together, and if you’re wanting to implement a blog site, the existing tutorials look as if they’d work fine for that.

Those of us who need to roll out a set of non-time-sensitive pages (i.e, no diaries, logs, or news items), and haven’t yet managed to grok the fullness of Textpattern’s conceptual net, could probably benefit from a quick summary of how to specify something like this.

In particular, navigation to specific articles is pretty well defined for blog postings and news articles, and there seem to be three main methods:

1. Go to the front page of the site and read whatever is there,

2. specify the URL of the article you want, or

3. look through the article list.

But if the content I want to put up is less like news items and more like topical articles that aren’t going to change much over time, a different kind of navigation would seem more useful, e.g., a hierarchy of topics, subtopics, and sub-subtopics.

I see among the “let’s see yours then” listings a number of sites put up by companies promoting their products and/or services. If I could find an explanation of how to organize this kind of site in terms of the Textpattern concepts of Sections, Pages, Forms, and Tags, I’d read it.

I’ve been thinking this must already be documented somewhere in the Textpattern Realm, and if I’ve been managing to overlook the utterly obvious, I welcome your correction, and apologize for being obtuse.

I had thought about adding a suggestion for a tutorial, but after reading the submission guidelines, I realize that I’m not an expert speaking from experience, and my suggestions may not be appropriate in that context. So I’m willing to be directed to whatever existing doc there is that explains, in terms of a fresh install of Textpattern, how to replace the handle of George Washington’s axe. And the head.

Destry · 2012-02-26 09:57:43

Hi Mixed,

Thanks for posting a very refreshing perspective. I understand what you’re saying. In fact, I some times wonder if it would be better to not provide any default template in Textpattern at all—just a clean canvas—and approach documentation in a real ‘from the canvas up’ kind of way. Or go the other end of the rope and make a blank page the default view, and then one of the first things people do after installation is choose a ‘genre’ of template that then quickly shapes the base structure for the kind of site they want. The latter is what the current default template does, in a sense, but it just favors the blog style layout, which is what most people probably needed in 2003.

Nevertheless, everything you’re talking about—classic pieces of website construction, if I may—is easily done with Textpattern, and I’m not so sure the semantics of the system (Sections, Pages, Styles, Forms, Tags…) are so much “out of alignment”, with the exception of Forms, which definitely is in terms of it’s name….

Sections — These are the sections of your website. As far as I can remember, I’ve called the lateral topic areas of a website’s construction “sections”, and it’s exactly the same here. Call them your website’s “parent topics” if you want, but it’s the same difference.
Pages — Web template pages. Where the HTML markup goes. Call them templates if you want, but same difference.
Styles — CSS style sheets. Same difference.
Forms — Ah…now here’s the outlier, but we all know it (and hate it). To most minds this means a web form, like you enter data into, but in Textpattern parlance, it means a ‘piece of code or text or combination of the two’, and the code can be HTML or Textpattern Tags, or both (and usually is). I recently noticed reference to forms as “code partials” on the “Build” slide on the Txp homepage, and I think Partials is an excellent term for Forms and should be changed in core at first feasible opportunity.
Categories — You have content topics (child-level organization of content within each parent Section) organized in categories. Same as it ever was.
Tags — Tags are exactly the same in concept as HTML tags, and these, my friend, are where the real power, simplicity and elegance of Textpattern lies. There are core tags, of course, and you’ll find that people create custom tags for their respective plugins too. They all work the same way and together (when a given plugin is installed). They are put in the location of your markup (whether in a Partial or Page) where content and/or code will be inserted when the page is rendered. (

Textpattern Architecture is like Information Architecture but specifically combining the Building Blocks of Textpattern.

All of these building blocks make a Textpattern website modular, and that’s why I like the term “building blocks” instead of “semantics” which is a pretentious and confusing word.

I also find it helps talking about Textpattern site construction with people in terms of the Russian doll model, where a small doll in placed inside another, that’s put into another, then another, etc until you have all the dolls neatly assembled into a single large doll. I’ll probably write another article sometime around that analogy, but here’s the concept…

Tags (and HTML markup) are the most fundamental blocks (the smallest doll). They can be mixed and matched to create “Partials” (Forms) of code (the next largest doll), or put directly into Page templates (the next largest doll). Pages, are assigned to Sections (the next largest doll; your topics as reflected by a main navigation, if you prefer), and all together make up the entire website (the largest doll all assembled). That’s simplifying it quite a bit, but it’s really no different than that.

The key for you, is to try and get into the mindset that nothing—and I mean NOTHING—is fixed in Textpattern. If you don’t want dates and authors on articles. Easy, don’t use the date and author Tags in the Partial (Form) that defines the content output for a given Section. Remember…Russian doll construction.

Also, you’ll see a lot of people talking about conditional Txp architecture, which is sweet stuff, but it’s advanced Tag construction. Don’t get thinking you have to do it like that at first just because a lot of people seem to be. All that means is they’re using fewer dolls to build the same site, but you can just as easily use a separate Section/Page match up for each topic section of your site, etc. In fact, I recommend you start out that way because it’s easier to get the hang of things when it’s not tightly wrapped together like a DNA helix.

Keep tinkering. There will be a point, probably soon, where you’ll just go. *Ahhhhhh. I get it!”

Textpattern CMS

Textpattern CMS support forum

#13 2010-12-15 03:06:36

Re: [wiki] Wiki homepage content

#14 2011-07-22 15:20:15

Re: [wiki] Wiki homepage content

#15 2011-07-23 08:54:28

Re: [wiki] Wiki homepage content

#16 2011-07-24 20:54:12

Re: [wiki] Wiki homepage content

#17 2011-07-24 21:25:42

Re: [wiki] Wiki homepage content

#18 2011-08-04 13:03:54

Re: [wiki] Wiki homepage content

#19 2012-02-26 03:03:07

Re: [wiki] Wiki homepage content

#20 2012-02-26 09:57:43

Re: [wiki] Wiki homepage content

Board footer