Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#1 2009-01-19 12:38:14

saccade
Plugin Author
From: Neubeuern, Germany
Registered: 2004-11-05
Posts: 521

[wiki] Referencing to Figures

There has been discussion about figures and referencing to special parts in figures with numbers (here , here and here.

I’ll call those numbers or references to items within figures “pointers” from now on.

These problems have to be considered:

  1. Textual pointers in headings (actually written, like “see (3)” or “(see Figure 12, number 5a)” as up to now) make the appearance of headings messy and spoil quick orientation (contrary to their task)
  2. Even when they are moved into normal text, they cause lots of maintenenace work, when something changes. You have to find out every single place, where a pointer is used – even in other pages!
  3. If placed in headings they will go into direct-links, thus causing another level of maintenance.

So somehow it seems reasonable to get rid of them.

But on the other hand pointers – if handled careful – can add a very useful visual help for people, who are new to something. Even site administrators may be completely new to a concept or way of handling something. For example you need less words to describe exactly, where something has to be entered.

Of course you could cut down figures to exactly show one single item and refer to the figur – but then you would have the same amount of references to figures as you would have pointers. And you will loose perspective and overview. For explaining things it is essential not only to (tunnel) focus on the actual topic, but also to have a sense of
  • where you are, and
  • where you will/can go next,
  • sometimes: where you came from.

So figures of bigger areas in a panel are essential.

A solution using both: bigger overview figures and small item figures will mostly make a page messy.

So I think pointers are useful things – if handled wisely.

As Textpattern now is much improved showing labels of most items to describe, someone could argue, that we don’t need any detailed figures at all.

That is true and we should follow these labels exactly – even in grouping descriptions or thinking about terms. E.g. “Category” and “Section” assignment now is connected in “Sort and Display” – and the Write panel description has been edited along this line.

But should we get rid of figures at all or simply show them as decoration? That may be true if the readers are strictly textadapted, but even then, they have to find, where the mentioned place is.
It really can help, showing a thing.

I’ll try and propose a solution for both views in the next post

(I’ll try to avoid writing monster posts :-) I think I’ll post it in three posts – included this one – please be patient)

Offline

#2 2009-01-19 13:14:42

saccade
Plugin Author
From: Neubeuern, Germany
Registered: 2004-11-05
Posts: 521

Re: [wiki] Referencing to Figures

Pointer Solutions, part 1

possible “quick and dirty” solution 1:

Given the relation between sub-headings in TextBook pages and the improved captions in Textpattern, locating is much easier than before.

So maybe we could use simple marks (forms and/or colors) which can be referenced/pointed from within the text, e.g. “(see Fiure 3, red dot)”.
As marks we could use some of the symbol entities in HTML, which are available in standard fonts and browsers (but that has to be checked careful).
Or we could even use one and the same color mark, which simply marks the places where something is explained.

So the places could be found more easily without numbers, and so there is no problem of re-numbering if something has to be added.

But there are limitations
  • There are not as many distinct symbols as maybe used.
  • There is no visible order (which might help sometimes in an additional perspective).
  • If used more than once on a side there may be confusions. (For this reason in my current edit of “Write” I provided a continuous numbering, which gives each item a number and keeps this number even in different figures).

This solution would help in one aspect, but there is another better solution in the next post.

Offline

#3 2009-01-19 15:05:25

saccade
Plugin Author
From: Neubeuern, Germany
Registered: 2004-11-05
Posts: 521

Re: [wiki] Referencing to Figures

Pointer Solutions, part 2

solution 2 with semantics and webstandards in mind:

Thinking about the different aspects of pointing I figured out, that most of the problems arise from mixing content and presentation.

I’ll point that out (don’t want to Kalauer) with a few approaches:

A) Have a look at the media references are made of: In the text we have characters as pointers. In the figure there are symbols as targets, represented by pixels. These are different things and don’t even match visually. Our pointers are cross-medium. Think of screenreaders, which will have to deal with content of no use, because they cannot solve the question where the target is. In consequence: A more consistent approach would be the following: Let the pointers in the text paragraphs be of the media type image or pixels too. This thought thoroughly we should have two levels of information:
  • A neatly carved text, which makes the most out of captions in panels and refers to them in a appropriate way as if there were no figures.
  • And a second level of visual information, which shows bullet numbers in figures and bullet numbers within text, where needed to point to a figure. An alternate text will do the standards thing (but for essential details see below).

Of course the problem of maintaining and keeping a correct sequence of numbers (e.g. when something has to be inserted) will stay.

B)
The second approach regards the separation of content and presentation.
At the moment in this area we are mixing content and presentation.
Let me point that out:
a) Our content in fact is completely independent from any visual presentation. The content is simply e.g. “pointer to the module ‘Sort and Display’”. Whether this is a number (and which) or a symbol is quite another matter.
b) If it is a number, symbol or merely a coordinate on screen is a matter of presentation.
c) My proposal basically consists of separating content and presentation in this realm.

When pointing to “(see Figure 3, number 6)” this is hardcoded presentation. When – as proposed in approach A – the media will be used in a conform way using images in pointers, this also could be done in a hardcoded manner (. But it could also be done in an intelligent way.
  • hardcoded manner: if a bullet number pointer is placed as an image file that represents the target by a number. E.g. place the image file “12.gif”. This way would be of no better use than saying “(12)”. You also have to find and change all occurrences, when 12 doesn’t point to “12” any longer, but to “13”.
  • intelligent manner: instead place an image file, that represents a target by its content. E.g. if you want to point to “Sort and Display”, place an image file named “sort-and-display.gif” or if you like “pointer-sort-and-display.gif”. This is based on content. In this way, the presentation is now independent. You can load the image with a pixel-12 – and later, when the numbering changes in your figure, you simply upload another pixel-number, e.g. pixel-13 to that image file. All occurences of that pointer image will be changed instantly without the need to know, where they have been used. Regarding Text/Image relation make sure the alternate text reads “pointer to ‘sort and Display’”, so that even screenreaders will say something that makes sense, or users without loading images can see what is meant.

So this is my proposal of separating content and presentation for pointers to get rid of maintenance and raise flexibility:

  1. Make the text as good as possible without figures.
  2. Use images as pointers.
  3. Name these images based on their essential content (the target in words, not any sign or number). And give them adequate alternate text.
  4. Load the images with the correct presentation.

This way will separate content and presentation for pointers and get a more intuitive relation between pointer and target as well as keeping standardscompliant and accessible.

I must admit there are two smaller things to be solved. In the next post.

Last edited by saccade (2009-01-19 15:20:22)

Offline

#4 2009-01-19 15:14:20

saccade
Plugin Author
From: Neubeuern, Germany
Registered: 2004-11-05
Posts: 521

Re: [wiki] Referencing to Figures

Ok, I haven’t much time left, so only a short descriptions of issues:

  1. When simply naming the pointer images after their targets, this will lead to the same presentation in all pages – so I understand the mediawiki mechanism which manages images across pages. If you want to keep presentation inside a page, then the page-name should be added to the image-target name (lika a namespace). But maybe there are better Wiki-Mechanisms.
  2. Another problem is versioning: the Wiki manages different versions of images, this seems to be ok. But obviously it doesn’t apply them correctly, when displaying a former version of the page? I tried, but it seems to show only the current version – what would be a problem, … ah, no, not really. Pointers and targets would of course match (wow, my system works!) :-) they only wouldn’t truly reflect, what a “versioned” user had seen at that time. Because he may have seen a “12” while I see a “13”. But that doesn’t matter as long as the pointer points to the correct target.

So far.
Sorry if anything is unclear. I tried to show the way I came to that solution as well as explain it’s mechanism in detail.
Simply ask.

Last edited by saccade (2009-01-19 15:20:50)

Offline

#5 2009-01-19 17:22:15

saccade
Plugin Author
From: Neubeuern, Germany
Registered: 2004-11-05
Posts: 521

Re: [wiki] Referencing to Figures

Here I’ve done a quick and dirty example of what I’d propose (I hope this is acceptable, if not, please forgive).

If you go one version back , you’ll see the pointer at the beginning of the paragraph.
Surely should tweak positioning and get rid of the link – at least the underline.

I’s in fact not too quick and dirty (save the places). From the viewpoint of code there isn’t anything more difficult. Code example below.

I’ll post a screenshot as well later. Done

And here the other one:

Here the Code, which is behind:

''Comments'' [[Image:pointer-comments.png|Pointer to Comments control]] controls two things: With a pair of on/off radio buttons

Nothing more. Maybe there is a MW-code for leaving the link.

For better management I’d suggest, that in the comments to the related Figure-file the marked places/modules are listed (or better: the matching filenames). I provided an example (had to upload the same image again, because I couldn’t edit the comments otherwise).

Last edited by saccade (2009-01-19 22:17:50)

Offline

#6 2009-01-19 22:27:52

saccade
Plugin Author
From: Neubeuern, Germany
Registered: 2004-11-05
Posts: 521

Re: [wiki] Referencing to Figures

So far I outlined, what I think to be a good and maintainable way to have both ideas of good documentation
  • well carved text with no need of cluttering images (best: no need of images at all)
  • and a second level of visual approach which can transmit additional information or simply help those, who have benefit from visual perception.

At least I think the idea of separating content and presentation in pointers (by using image-filenames like tags) is worth considering.

Thanks for your patience! Now I’m very interested in comments. :-)

Offline

#7 2009-01-20 20:34:00

saccade
Plugin Author
From: Neubeuern, Germany
Registered: 2004-11-05
Posts: 521

Re: [wiki] Referencing to Figures

Being a great fan or follower of Bringhurst’s “The Elements of Typographic Style” and because I like minimalistic but sophisticated designs of course I’m also concerned about too much visual clutter.

So I’ll explain what I did in the current Write so far:

In the images I provided so far I tried to reduce clutter as much as possible
  • leaving arrows where possible
  • reducing colors (I simply would use only one single color, which is used nowhere else save pointers and comments in images. There is only one exception explained below.)
  • providing a ‘holistic’ concept of pointers:
    • I’d show a “visual table of contents” at the beginning: A complete figure of a panel and within this all pointers/numbers, which will be used in a page – thus we’ll have an overall plan of explanation and a quick orientation system, if for excample someone simply want to read something about “this new field in the lower left panel”. Those numbers with the exception of the first to be explained in the section immediately following after the figure I would make gray as ‘inactive’. Only as a hint what will follow on this page. In “Write” see Figure 2.
    • The following cropped images/figures should only show, what is explained in a section, thus normally all pointers are in red. In “Write” see Figures 3,4,6,7,9,10,11.
    • Only if it’s more convenient to show a bigger crop, without explaining all of the parts, there also will be left some gray pointers. This is the case in the special way publishing controls are presented, because they come in two portions. This is reflected by a few gray pointers left. In “Write” see Figure 8.

In the design I tried to get as clear and distinctable pointers as possible. For the first review I ended with those 24×24 px bullet numbers. Because of readability/legibility I made them “positive” with a circle round them.
Example and of course above in the screenshots.

But of course this might not please everybody. There is a double color-border-contrast by the circular outline, and they are big in contrast to text they’re pointing to. So I looked for another solution.

Now I’m working on another design, to reduce more “clutter” and now I have smaller 18×18 negative bullet numbers in work. Those also would fit much better into copy text. See an example here:

I’ll present an example with those in use later. You can see an example in the german “Write” = Verfassen
There Figure 2 and below the pointer to the article view tabs (presented by a “1”).

Last edited by saccade (2009-01-20 21:22:42)

Offline

#8 2009-01-20 22:05:13

saccade
Plugin Author
From: Neubeuern, Germany
Registered: 2004-11-05
Posts: 521

Re: [wiki] Referencing to Figures

A last post today: Screenshot from the german “Write”-panel, showing anexample of the newly carved bullet numbers.

Last edited by saccade (2009-01-20 22:05:36)

Offline

#9 2009-01-20 22:15:31

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,250
Website GitHub

Re: [wiki] Referencing to Figures

Thanks for all the input on this topic, Michael. Sorry to leave you with the impression you’re having a monologue with yourself for so long :-)

Looks good, and the visual cues are nice to link stuff together, because you can quickly scan the pictures for the thing that you don’t understand, note its number and jump straight to the corresponding bit of text with that same number. I’m not sure if it might become a “sea” of red numbers on complicated pages such as Advanced Prefs; that might further clutter the page as you scan for the correct number. But it seems to work well on the Write page.

When I get a chance I’ll look at the markup in more depth that you’ve used “behind the scenes”, and have a play with it on a test page. Once I get to grips with it and do some ‘pretend updates’ as if I was editing someone else’s page, I’ll let you know more of my thoughts.


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Offline

#10 2009-01-21 09:52:14

Destry
Member
From: Haut-Rhin
Registered: 2004-08-04
Posts: 4,909
Website

Re: [wiki] Referencing to Figures

Damn, saccade, that’s a regular thesis. :)

Sorry to be late in here. I’m juggling about 5 things, including this dialog, and 3 have higher priority at the moment.

I have the same concerns as Bloke about all the red “pointers” being more distracting than helpful (and they still seem to be a lot to manage). From my first, quick pass through your proposal, I don’t see where the original situation has changed much except pointers in the copy are now red instead of black, and a bunch of bright, red dots on white background is distracting (unless one is color blind).

For example, you sayI’d show a “visual table of contents” at the beginning: A complete figure of a panel and within this all pointers/numbers, which will be used in a page”. Well, this was more or less what we did to begin with, and why we are here now — it was too much to maintain (and arguably information overload). There’s another problem with this too — image size. We don’t have the real estate to be showing complete screenshots at the top of copy. Indeed, that was a conscious redesign consideration (narrowing the article body column) to help eliminate exaggerated images (e.g., screenshots) and make text line lengths more readable.

I do agree, as you show here, on making a series of images for each panel article that visually focus on one widget at a time. In comparison, I don’t agree with using images like shown here that group several widgets together. That’s going back to the initial problem of images being too large and too many pointers to manage.

One consideration of design that you didn’t mention in your proposal (unless I missed it), which is an obvious and often used one in print and web media alike for helping to make the relationship between copy and images more clear, is position — layout. It is my belief that if we use images that are focused in size to a single widget at a time (which is intuitive when you think each widget represents its own section of headed copy), and orient images left/center/right to the associated copy (as appropriate to image size, or to create a staggering effect), then its possible to describe the functions and options in a given widget without all the hassle of pointers at all.

The following image is a model to give indication of what I see being appropriate and easy to maintain.

———————

To be clear about how to describe a given widget’s components without using red pointers, let’s consider the right column on the Write panel, which is composed of five fieldsets (Status, Sort and Display, Comments, etc). Taking the first one, Status, as an example, I would simply treat the section on the wiki page as shown in the following image. (Note the copy is also an example of being refined, but could perhaps be even more so.)

———————

By using 1) a focused image in physical relation to its copy, 2) a figure reference in the intro text, and 3) clear, descriptive (but concise) copy, there’s no need for any pointers at all in either the image itself or in the copy. It’s perfectly clear to a reader what is being described and where. Also note this model has no need for a special class to make “header extensions” (contrary to what is suggested in the first image above); we simply use the semantic hierarchy of regular Hn headers.

This is the best model, in my opinion, and the one I would like to see in the English pages.

However, I am certainly not against translators wanting to use a different visual model in their native language pages, especially if it’s appropriate to that culture’s publishing conventions, but I would recommend keeping it simple or few will step up to lend a hand with the translating and editing work, presumably.

Last edited by Destry (2009-01-21 10:01:24)

Offline

#11 2009-01-21 17:56:19

saccade
Plugin Author
From: Neubeuern, Germany
Registered: 2004-11-05
Posts: 521

Re: [wiki] Referencing to Figures

Hi Destry,

@“thesis”: I’m simply very committed to Textpattern, so I’d like to give it a good thing!. At the same time I would like to help TextBook to go step forward. It’s a pity, that there isn’t a full description yet after years. So I gave me a kick up the backside to contribute and do what I’d like to see: Full and very helpful documentation.

So let me defend my thesis:

There are a lot of improvements, which I must admit might be hidden, if you only have a first glance.

  1. Reduction of clutter by reducing useless elements and ambivalent colors and by using a consistent simple system.
  2. Reduction of maintenance efforts by separation of content and presentation.
  3. Adding a clearly distinct and well thought visual layer of information.
  4. Working out an intuitive system of overview.

These points of course are useless marketing talk if not proved.

But I think I can prove them:
(I will do so in separate posts, quickly following)

Offline

#12 2009-01-21 17:58:03

saccade
Plugin Author
From: Neubeuern, Germany
Registered: 2004-11-05
Posts: 521

Re: [wiki] Referencing to Figures

@Reduction of clutter by reducing useless elements and ambivalent colors and by using a consistent simple system.

There is now a simple visual system of only one form, a small circle with a number in it. No arrows or lines (which won’t add information), but simply position markers. [Ok, there are the column brackets and names – they are a special case and no default. Leave them out if you want. They simply try to get interchangeable names for communicating function clusters. They surely could go into the captions.]

There is only one active color, which clearly indicates the pointer layer and is strictly used only for it. (The other color – if you’d adopt the whole proposal -, gray for inactive pointers is only used sparely in an intuitive context. It is widespread conventional for an information which is indicated but in the moment not in the focus.)

“Clutter” in my eyes is also needless pointing to figures by means of text. If using pointer images where appropriate, you normally could leave out a “(Figure x)” at a lot of places. I’d say: Let visual things point to visual things – (textual info if needed is present the alternate text).

On clutter: What you propose (crop images down to single widgets) would lead to a lot more figures – with frames, captions, references to those figures. I’m afraid this doesn’t lead to shorter pages, but instead to longer ones. Imagine the two “publishing controls”-figures and in compare a bunch of six (or seven incl. “more”) cropped ones – each with an own figure number and a caption! And it will blow up maintenance effort, if you’d have to do a recount (on maintenance see below).

Offline

Board footer

Powered by FluxBB