[wiki] Tags Reference

Destry · 2008-10-24 13:40:21

Els wrote:

… an extension like that might very well help to attract more contributors…

Unfortunately, that extension does not work with new MW. Not surprising since it was last updated a year ago. Would have been interesting though.

Side:
Page TOC’s are back in action, except main (Index) page which is removed by desire.

els · 2008-10-24 15:49:14

Trying to post a Textile link to an anchor on a Tag Reference page, I found that when the heading (and therefore the anchor name) ends with a full stop (.), the link does not go the anchor. Obviously this is a Textile issue, but is it nevertheless worth while to take into account when creating headings?

Bloke · 2008-10-24 15:54:14

(I’m not stalking you, honest :-)

Els wrote:

when the heading (and therefore the anchor name) ends with a full stop (.), the link does not go the anchor.

That’s a good point, well found. As it happens (purely luck than judgement) I’ve been removing full stops in headings when I see them. Phew.

Guess when we’ve all gone through and tidied the headings up to be a lot shorter (that one you posted there is a true monster!) it should go away for the existing tags and we can textile to our hearts’ content.

Last edited by Bloke (2008-10-24 15:54:48)

els · 2008-10-24 16:03:19

Bloke wrote:

(I’m not stalking you, honest :-)

I don’t mind, as long as you keep agreeing with every post I make ;)

As it happens (purely luck than judgement) I’ve been removing full stops in headings when I see them. Phew.

Yes, I’ve been doing that as well, but not very consistently as it appears. Ah well, one more reason to tidy up :)

Last edited by els (2008-10-24 16:03:55)

Destry · 2008-10-24 21:18:29

It is generally bad form to use ending punctuation in titles and headers, with the exception of a question mark. The periods exist because the headers were used like descriptions, which is unconventional to say the least, but makes for difficult reading/scanning too.

I may not have got the details right, but here’s a change towards the right direction, if_article_list. Each example now has an easy to scan header and a more descriptive explanation (under the header). And note how much better these headers work in the TOC.

By the way, you both rock, and the community should be giving you high fives for the dedication and level of detail you’re putting into it. Great work!

els · 2008-10-24 21:28:06

Destry wrote:

By the way, you both rock, and the community should be giving you high fives for the dedication and level of detail you’re putting into it. Great work!

Who needs a Social Rewarding extension when we have Destry :) Thanks for your kind words!

Your if_article_list page looks much cleaner now! I’ll try and put some time into the other pages this weekend.

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

Textpattern CMS

Textpattern CMS support forum

#91 2008-10-24 13:40:21

Re: [wiki] Tags Reference

#92 2008-10-24 15:49:14

Re: [wiki] Tags Reference

#93 2008-10-24 15:54:14

Re: [wiki] Tags Reference

#94 2008-10-24 16:03:19

Re: [wiki] Tags Reference

#95 2008-10-24 21:18:29

Re: [wiki] Tags Reference

#96 2008-10-24 21:28:06

Re: [wiki] Tags Reference

#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

Board footer