[wiki] Tags Reference

Destry · 2008-10-30 22:28:19

Definition lists in the wiki are now styled by default so that <dt> is bold and <dd> has a small arrow bullet. I think this works good as a default because it makes it immediately clear when something is in fact marked up as a definition list in the wiki (authors tend to abuse these when they don’t know the syntax well, so this is like a visual confirmation of a dl done right when it is). It also adds good distinction to the list information, making it more scannable. Where this would be especially useful, naturally, is in tag pages.

See the article page as an example, and especially:

under the attributes section where each attribute is parsed into descriptive, values and default dd items, when they exist.
under the examples section, for instance Example 1.

In the latter case, this is a new thought. It’s not something anyone has to go back and fix everywhere, it’s more for thinking about when making revisions or creating new pages. The idea stems from the fact people have commented many times about the clarity and value of the tag examples, so perhaps one way to improve the quality overall is to adopt a structure that lends to creating less arbitrary as a result.

So Example 1 on that page begins with a short, concise header (instead of the long header/description that plagues many examples in the Tag Reference). Then immediately under that is the code example, then under that is a definition list having two dt/dd pairs aimed at clearly describing the code and why a user might use it; the <dt>’s being:

What this does…
Why you might do it…

If you think about it, these encourage better tag examples. The first part is not too difficult, mainly just explaining the mechanics (e.g., attribute functions) of a given tag code example. This is where most examples stop though and that’s not enough to give users context. The second part is arguably the more important for the learner and, not surprisingly, is more difficult to write. I would go so far to say if you can’t provide details for the “why you might do it…” part, then the code example is not a good example to begin with. Provide both parts for any given example, and the example will be a good one.

Just something to think about.

(On a diff note, I’ll be testing the PDF Book extension in the near future to see if it lives up to it’s objective — printing the entire Tag Reference as a single PDF file.)

els · 2008-10-30 23:13:47

Nice! Both attributes and examples look a lot cleaner now. And I think the ‘Why you might do it…’ part is a very helpful addition.
(Content-wise: the article tag doesn’t have a section attribute ;) (example 1))

Bloke · 2008-10-31 17:10:04

Destry wrote:

Definition lists in the wiki are now styled by default

<echoing Els> Nice. I like the description first then the values if applicable and the default last.

I’ve modded a few to fit this new format (title, error_*, txp_die, text, thumbnail, and will work through some more when the excitement at going to see the new James Bond movie subsides… I know, there’s no hope for sad people like me… :-)

Where appropriate I’ll also go back and fix the over-long example titles, do the ‘what this does/why do it’ dd lists and bring the markup into line with the article tag.

One more possible thing — and this may be my lazy gene kicking in — but some of the changes in 4.0.7 are very minor. For example, the thumbnail tag (among others) is having its default behaviour changed from escape="" to escape="html".

Now, I could be a good boy and make a new tag in the Future Tags namespace/category, edit the att and note the change in the genealogy, but would there be scope for something akin to a <txp:hide> in the wiki? Maybe just a style rule .hidden { display:none; } so as I find defaults or minor edits like this during the trawl I can ‘prepare’ the tag for the changeover? Then it’s simply a case of removing the surrounding div (or whatever hiding mechanism) from the markup and the new page is ready to go. I notice there’s a .hiddenStructure class rule already; would that be suitable?

The downside I suppose is that the tags that have changed or are going to change are not flagged in their own section and therefore might be missed on changeover day. But by the same token they don’t automatically go into the Future Tags area by themselves, so someone has to do the legwork of moving it over (and back) anyway.

Like I say, if that would cause cataclysmic confusion or be more hassle than it’s worth then I’ll do it the ‘proper’ way and make a new tag in the appropriate location for tags that are merely changing a bit, and do a full page copy/move when the time comes. ~~Maybe the Future Tags area should be renamed Future Changes or something, with subcats “New tags”, “Changed tags”, etc or is that just over complicating stuff?~~

EDIT: Just found the Tags In development section, so scratch that last bit; assuming this page structure (or something akin to it) is going to be used for the new wiki.

I’ll be testing the PDF Book extension in the near future

Go go go!

Last edited by Bloke (2008-10-31 17:31:55)

Destry · 2008-11-02 14:17:21

Bloke wrote:

Just found the Tags In development section, so scratch that last bit; assuming this page structure (or something akin to it) is going to be used for the new wiki.

After reading your post, I’m not sure what it is I should be doing. Maybe we don’t need the category:Future Tags …rather just use Tags In development instead?

Bloke · 2008-11-02 16:12:56

Destry wrote:

After reading your post, I’m not sure what it is I should be doing.

Darn, I’ve over-cooked a post again :-( Will try harder to be more concise!

Maybe we don’t need the category:Future Tags…rather just use Tags In development instead?

Yeah, perhaps. The tags in development page does give the scope to break it down somewhat more usefully to include a sub-category per dev branch and/or further breakdown into ‘types’ of tag (New tags; Modified tags; Tags that have not changed but have just had one of their defaults altered; and so on)… /me thinks of an index page that acts like a global “changelog” or genealogy for tag updates/development

Tags in development
- 4.0.7: New tags
  - rsd
  - variable
  - if_variable
- 4.0.7: Modified tags
  - article — links to the updated (cloned) article tag to show its new syntax (so people using SVN can find or create docs), but when 4.0.7 is released and the changes are reflected in the current article tag, this link is changed to point there instead
  - category_list — ditto
  - …
- 4.0.7: Minor tag changes
  - thumbnail, image, article_image, file_download_description, link_description, and link_name now all use escape="html" by default
- 4.0.6: New Tags
  - …

I suppose technically, that ‘minor changes’ subcategory is a class of tag modification so perhaps there isn’t a distinction; it’s either “New” or “Changed”, no matter how trivial. In that case, hiding stuff in the existing tag pages in preparation for the new release is not a valid method we should promote.

Last edited by Bloke (2008-11-02 16:14:52)

Destry · 2008-11-03 10:56:00

I added Tags In Development to the Tag Reference mininav, replacing the link for Future Tags. However, I kept future tags and made it a subcat of the Tag Reference. Since even new tags have their own descriptive wiki pages, respectively, it didn’t seem like a bad idea as you can easily change the category assignments as the tags become production.

As for the communication on the Tags In Development and category:Future Tags pages, I’ll leave that to someone else who might know better what to say.

Bloke · 2008-11-03 11:44:50

Nice one, thanks. I’ll have a think about what to say on the Tags in Dev page, and how to organise it to make it usable and maintainable.

els · 2008-11-07 23:58:55

I’m still going through the tag pages, to tidy up the attributes lists where needed, and also to try and shrink the examples’ headings. I’m skipping the ‘What this does’ and ‘Why you might do it’ part for the time being, unless something immediately comes to my mind (which does not happen very often I must confess).
Is it OK if I remove a totally unhelpful example now and then? (Like: who on earth would want to display a hyperlinked category name… ?)

Destry · 2008-11-08 22:59:42

Els wrote:

Is it OK if I remove a totally unhelpful example now and then? (Like: who on earth would want to display a hyperlinked category name… ?)

Anything you do can only be appreciated. As for pointless examples, I would say yes, delete them. If it’s not functionally relevant, then it’s not teaching anybody anything helpful (an aspect of poor docs).

Destry · 2008-11-14 19:12:17

This should make some folks happy.

gomedia · 2008-11-15 00:43:24

Destry wrote:

This should make some folks happy.

A downloadable version of the Tags Reference makes me very happy – sometimes you just need it on paper!

It’s great to see the Textbook being given some well deserved attention.

A couple of suggestions/requests:

any chance the Alphabetical Tag Reference could be restored to the quick links?
with my browser width at 990px, text is jammed right up against the left edge and I get a horizontal scroll bar
- it would be easier on the eyes if there was a bit of white space along the edges
- changing all the widths from 984px to 800px (say) would give the pages some horizontal flexiblity & get rid of the scroll bar on smaller window widths

Your hard work is much appreciated. Thanks.

Destry · 2008-11-15 12:53:20

gomedia,

The side margins are certainly important for narrower resolutions, and I guess I just forgot them. Consider those coming.

The other two points, however, were not overlooked; decisions were made in these cases:

The new Tags Reference was intentionally created to replace the static Alphabetical Tag Listing so to gain the auto-alphabetizing functionality as well to make it possible to use things like the PdfBook extension easily (i.e., lower overhead and improved benefit). To my mind, it makes no sense to maintain a static, redundant list manually (and who is going to do it?) when the wiki category does it so much better now, thus the ATL should be phased out, not promoted. I was going to remove the page and just haven’t got around to it. (Ed. — However, if all you need is a printed page of the alphabetical listing, then you can still use the browser’s print feature to print the Tag Reference category page itself. There’s also another PDF extension we can try that downloads a single page PDF.)

It was also intentional and openly discussed to target the design to a 1024 resolution, for a couple of reasons:

It’s a fairly common target for designs these days, and we could point to many sites like ALA, Boxes and Arrows, UX Matters, and a slough of others that use this model, thus they too get horizontal scrolling.
More importantly that what the Jones’ are doing, we are talking about a wiki here having in some cases four columns (in grid terms) plus images in page context. If we narrow the design up even more, or make it flexible, then we likely make for ugly page content display in places like the Admin-side and Tag Reference pages; even cause complications where images and floated mininav boxes start overlapping each other. There’s also the consideration of making pre box content (i.e. block code examples) line wrapping more than they already do, which some people don’t like as it is (personally I think line wrapping is better than code busting out the right side of the main column or having many in-page blocks with horizontal scrolling). I wanted to go with something narrower than the default full-width, liquid design from before, but also add some finite limits to safely work with content types and layout.

We’ll see what kind of fixing and wiggling we can do, certainly, I promise, but I don’t want to get caught up in catering to every backstep request that comes up (like supporting IE5 on mac and whatnot).

Last edited by Destry (2008-11-16 11:03:48)

Textpattern CMS

Textpattern CMS support forum

#97 2008-10-30 22:28:19

Re: [wiki] Tags Reference

#98 2008-10-30 23:13:47

Re: [wiki] Tags Reference

#99 2008-10-31 17:10:04

Re: [wiki] Tags Reference

#100 2008-11-02 14:17:21

Re: [wiki] Tags Reference

#101 2008-11-02 16:12:56

Re: [wiki] Tags Reference

#102 2008-11-03 10:56:00

Re: [wiki] Tags Reference

#103 2008-11-03 11:44:50

Re: [wiki] Tags Reference

#104 2008-11-07 23:58:55

Re: [wiki] Tags Reference

#105 2008-11-08 22:59:42

Re: [wiki] Tags Reference

#106 2008-11-14 19:12:17

Re: [wiki] Tags Reference

#107 2008-11-15 00:43:24

Re: [wiki] Tags Reference

#108 2008-11-15 12:53:20

Re: [wiki] Tags Reference

Board footer