[wiki] Textbook Terms and Terminology

saccade · 2009-01-18 14:56:46

Now a technical question:
I like to give the following (already mentioned above) a try:

1) Plain headings where panel modules are referred to.
2) Interpreting “heading extensions” as in-line, err …, yes, heading extension. :-) Which should simply be specially designed text on the beginning of the first line after the related heading.
I wouldn’t tag it as ‘header’ because this would be semantically problematic causing another entry on the same level or a “false” sublevel – and of course also would result in another anchor on the page. So my thought is to simply tag it as a special class of text (maybe neatly designed). Class-name: heading-extension.

Of course I also could make a simple first sentence of it. But I think it should be a thing that is like a heading, helping to quickly decide what the section talks about and if the part is of interest. Somethig like an explaining label.

Reasonable?

But then I need a way to give text a class-span. And of course there needs to be a related style.
As a first solution I could give it a span with class and e.g. a color, entering the tags. But I need to know if this is acceptable editing or if there is another, better way.
And surely I’ll make a decent matching design.

Destry · 2009-01-18 17:10:47

Sure, I can add a custom class for this, but I’m having trouble visualizing what your getting at exactly. Why don’t you throw a little text mockup together so I can see what you mean, and I’ll add the class rules.

saccade · 2009-01-18 17:19:22

You can (now) see what I mean directly in “Write”.
There see “Status”, “Section”, “Category”, “More”, “Timestamp” and “Expires”.
For the moment I formatted my “heading extensions” simply as “bolditalic”. Instead of that a span with class could give more control.
I’d like more space to the normal text or additionally maybe some separator symbol (Pipe?).

~~But I will make some mockups – only at the moment I have to finish another job first.~~
Here a mockup – just a suggestion:

Last edited by saccade (2009-01-18 17:53:34)

Destry · 2009-01-18 17:50:25

OK, I see. So you don’t mean to have a line break, and thus it is indeed a span. Got it.

Standing by for the visual nonetheless.

saccade · 2009-01-18 17:54:46

Updated my post above.

Destry · 2009-01-19 00:26:18

OK. Details added to the inline styles help page.

Basically: class=“topic-lead”

I wanted to use a shorter class name because people will not like typing anything too long. Also, I want to avoid using the Txp brown because that is the wiki link color, so I made it a earthy green color which I think stands out but works OK with the brown and yellow colors too. The pipe is not added automatically, but done by author, if needed.

Last edited by Destry (2009-01-19 00:27:54)

saccade · 2009-01-19 06:37:03

Thank you! Fine color!

But I think there needs to be additional space. If I’d type the pipe, this must be nonbreaking spaces. To avoid using senseless nonbreaking spaces – and another thing to think of for contributors – , I’d use the following styles in addition to your definitions:

padding-right: 1.5em; border-right: 2px solid #858737; margin-right: 0.5em;

This will automatically (important for contributors!) give the heading extension a nice amount of space on the right, then a border-“pipe”, and another good amount of space before regular text starts.

Edit: I added the topic-lead-spans to Write, so you can see there, what it looks like.

Last edited by saccade (2009-01-19 06:44:33)

Destry · 2009-01-19 09:18:06

I’m not keen on the pipe idea for a couple of reasons:

First, and most importantly, using a pipe to separate a header from it’s subordinate text is not a convention in written English. Since this is an English language page, I would like to keep things correct as much as possible, literally speaking. Two conventions that do exist are using a colon (:) or a dash (—), though the colon is more often used, for example…

Topic Header Lead: And the text would go here…

Topic Header Lead — And the text would go here…

Also, proper reference to an image/figure is by placing the reference in parentheses, so if you wanted a reference to follow the topic leader, then it would expectantly be like this…

Topic Header Lead (Figure 4a): And the text would go here…

More conventionally (in English), the reference would be placed at the end of the sentence where the figure is first referred to in context, so closer to something like this…

Topic Header Lead: This is text describing a function depicted in an associated image (Figure 4a).

This is the convention I would like to see, but as I mentioned in an earlier post, some of the panel images and the associated copy needs recreated and edited, respectively, to get rid of all that image numbering and lettering stuff, which is unnecessary to maintain going forward.

Second, we should want to keep all custom styles globally useful; that is to say, they can be used anywhere in the wiki, not just for an isolated situation. Otherwise, wiki styling could get out of control if everyone wanted a special class for a specific thing. The green, bold style has potential for being useful in a lot of instances, but not if it has a fixed pipe on it; and nevertheless, the conventions mentioned above still apply.

Lastly, there should not be a concern for blank spaces because the topic header should never be so long as to wrap to a second line, and even if it does, it’s not an issue if the (colon) convention suggested above is used.

Hopefully I’m not coming across as a wiki tyrant, but rather as simply maintaining consistency with English language conventions and the wiki style guide (which is represented by some of the wiki help pages at this point rather than a specific document).

saccade · 2009-01-19 09:57:41

OK, of course I understand the concerns, and maintaining consistency is an important task. I agree your thoughts.

I was much more thinking from the view of information design, and so wanted to have a minimalistic and simple but distinctly different style for the heading extensions. In essence simply a visual indicator the same way as making headings bigger size or underlining or keeping them vertically a little separate from the text above and below – (without actually putting things between).

Did you have a try, what it looks like?

In fact what I called “pipe” isn’t a conventional sign and I actually didn’t use it as an existent character but replaced it by a border (the same non-existent indicator as the heading underline) so it isn’t really there. It is something like a vertical underline for the heading – consequent, if it is running in andd hasn’t to be separated from below but from besides.

For the same reason I’d like to have additional space. Not because any wrapping, but simply to indicate it is another type of text.

I already thought of the other character-based solutions you listed. Dash is my favorite of these. It also would solve one problem, that exists, when using the visual approach outlined above: An indicator if there is no style.
Colon is something that is used in other semantic situations as well, – for example if you want to list something, or if you give an introduction, – so it wouldn’t indicate the special semantic content of the heading extension.

So if you don’t like the “vertical underline” then I think the Dash is the most appropriate. But it should be within the span, so it is green.

As for the globally useful span you’re right of course. But this span is labeled “topic-lead” and thus in my view it may have it’s own conventions. It even shouldn’t be used as a mere “green” for semantic reasons (when it’s content is no “topic-lead”).

The problem of references and figures and using numbers is another one. I already have a proposal, which will possibly be a good way to keep the good of all views. But I first have to write a proper text about it.

Hopefully I’m not coming across as a wiki rebell ;-) and I surely don’t want to offend you (hope I don’t). I’d simply like to combine decent helpful visual approachs with creative and well thought conventions (in fact the idea of running in heading extension itself is not really conventional too, but solves two needs: plain headings and at the same time more information in a heading-like manner).

Last edited by saccade (2009-01-19 10:30:31)

Destry · 2009-01-19 11:24:14

saccade wrote:

Hopefully I’m not coming across as a wiki rebell ;-) … I’d simply like to combine decent helpful visual approachs with creative and well thought conventions.

No worries. I appreciate the active thinking because it keeps it interesting. If nobody ever contributed thought to the wiki, I would lose interest too.

Here’s how it should ideally go down when creating copy for TxB or any docs project, because a wiki is, afterall, about documentation:

Keep the writing simple and concise: This is the most important because it influences how you do everything else; not to mention it’s the best for the user.
Use the native language correctly: With the exception of marketing-speak, perhaps (which is not the case here), there should never be a compromise on this. Documentation creativity revolves around the rules of orthography, not the other way.
Adhere to standards and semantics: When you combine this with #1, you often find you don’t need to be creative, not very much.

@All:

A couple things to point out to anyone listening here:

First, and critical — TextBook’s audience is Txp site administrators; the people who will be installing Txp and presumably setting it up for self-use, or the use of other people (such as web designers for clients). Unfortunately, I often see copy that is written to various audiences at the same time. This is confusing to a reader and results in verbose wiki copy. If you remember that your talking to the admin, then you don’t have to say things like this, for example:

“If any ‘‘Status’‘ you choose isn’t allowed when saving the Status, you will automatically flip back to the nearest status you’re allowed to assign. Here only the most important ‘‘restrictions’‘ are outlined – for in-depth information about privileges please refer to [[Users]].”

If it’s not obvious, the problem with that above is it’s not talking to the site admin who would never face a status restriction, rather it’s talking to a presumed backoffice contributor — perhaps an employee of the client for whom the site was developed. Thus, it’s confusing, verbose and unnecessary because it’s not speaking to the target audience.

The Status section of the Write panel copy is where that text was, in the blue note box, but I’ve removed it and edited that section to be more clear. User roles and their limitations only need to be defined in the Users panel instructions for the sake of the site administrator, and all further reference to roles should simply link to that page. That’s not to say that such information is not useful to the right audience, but in this case, it would be the web designer’s responsibility to provide their clients with the documentation explaining if this then that situations about Txp use at a level under the administrator. TextBook needs to stay focused to it’s true audience.

That’s just one example of our target audience mis-direct problems in the wiki. A dedicated editor is the only way we will probably ever eliminate problems like that, but we should still try and police it collectively.

Second thing I wanted to mention, don’t ever begin a section of text with a “Note”. The concept is you first present the topic’s introductory text (itself the first thing under the section header) and then provide any supplementary notes as needed under the introductory text. A note doesn’t mean anything if the reader doesn’t first know what the note is in context to.

By the way, there are wiki styles for notes, use: <div class="notes"><p>text copy here</p></div>, which are defined in the Help:Custom Block Presentation. It might be worth reviewing that page, as well as the collaborative Help:Page Status Flags.

@Saccade: Perhaps I will try and find some time this week to edit the entire Write panel page, including images, so that it might serve as an example of what I’m talking about here. Currently, the page is way too verbose and I would hate for any translations of it unnecessarily.

Last edited by Destry (2009-01-19 12:42:19)

jsoo · 2009-01-19 12:25:44

Destry wrote:

Keep the writing simple and concise: This is the most important because it influences how you do everything else; not to mention it’s the best for the user.

Omit needless words
(Rule #17, The Elements of Style)

I wrote such a long letter because I didn’t have time to write a short one
(variously phrased and attributed)

saccade · 2009-01-19 12:26:39

Oh, I see.
You’re right, I didn’t have in mind that it’s strictly administrators only.
Thanks for working that out. Status restrictions of course do not belong to this place then. (While I tried not to be confusing, verbose and unnecessary – but in contrary to make it as clear as possible and sort things out that belong to another page). :-)

For the other parts I really did my best to edit the Write panel in a way that it might serve as an example of what I’m talking about here – regarding concise terms, comprehensible steps and a full and helpful description.
This also is the reason why I sometimes described what you can do or how something can be achieved best (e.g. time management).
I know a lot of site administrators who are quite new to doing administration in the way Textpattern provides. In fact they often are new to site administration with a CMS at all.
Those I had in mind.

For this reason for example I tried to condense the headings structure to a simple and logical division of the main three “columns” (and thus solved the new/existing states different than before, when it doubled the third column explanation on the same level).

Of course “Write” now is very long.

I even thought about, if it could/should be splittet to a page triple along the columns.

I’d very much like Textpattern the CMS to begin and stay (!) with for a lot of beginning site administrators. I think it would be an advantage for Textpattern to offer them a widely thought documentation.

Bloke · 2009-01-19 12:47:24

Good points, well made by all. When I get free of my current client project I should have a bit of time to wander through the admin-side documentation and check it for coherency in the manner in which you describe. The last one I did with any degree of hard-nosed editorship was Basic Prefs but even that could probably be trimmed further.

When the Write page is at the stage where it demonstrates the modus operandi and we’ve chewed over Michael’s ideas for image management/reference, and the dust has settled, I’ll have a go at the Advanced Prefs page because it’s a mess. After ploughing through the Basic Prefs I just didn’t have the energy left to go through and rewrite the advanced page without knowing the best way to handle those pesky numbered images that all require regrabbing / updating.

My biggest bugbear — and Michael ~~will touch on this when he posts his ideas I’m sure~~ has done this while I was writing this post — is that any change to the admin side means redoing screenshots. On its own, that’s not much of an issue but if the screenshot is littered with what I’ll call “markup” (numbers, lines, arrows, etc) then that entire markup system needs recreating. This is not so much hassle if you happen to have the original Photoshop file (or whatever) but if the page is updated by someone else, the only avenue open to the editor is:

Open the existing .png/.jpg and alter it (if possible), then resave it and take the quality loss on the chin
Start again with the image from a new screenshot and mark it up to match what was there before
Start again with a fresh image, ignore the existing markup and alter the surrounding words appropriately

None are ideal. A straight screenshot would be easier to manage but I understand that pointing things out visually is sometimes a good idea to save cluttering the text with wordy positional information. Hmmmmmm.

Last edited by Bloke (2009-01-19 12:53:46)

saccade · 2009-01-19 13:00:36

Working my proposal out, I just wanted to drop a line here:

I think I would make a (mine) Photoshop file with layers available within the Wiki, which contains different screenshots (whole panel!) and all the pointers on layers (including additional ones). So – if there needs to be adjustment, someone could download the psd.file, rearrange the numbers or make additional ones visible, save a Webfile, and upload the new version of the psd-file. He/she also could crop a special part out of the whole file.
If there is a new version of the screenshot, it could simply be taken and added on a new layer. Noting to do save rearrange the pointer layers.

Does that sound reasonable?

Bloke · 2009-01-19 13:34:27

saccade wrote:

Does that sound reasonable?

Yup, if the wiki can be (ab)used in this fashion and Photoshop is the best tool for the job, then it gets my vote (aside from the fact the .psd file format is, like, 2 bajillion times bigger than most other file formats combined, and 90% of it is hot air or Adobe propaganda!)

Last edited by Bloke (2009-01-19 13:36:15)

Textpattern CMS

Textpattern CMS support forum

#31 2009-01-18 14:56:46

Re: [wiki] Textbook Terms and Terminology

#32 2009-01-18 17:10:47

Re: [wiki] Textbook Terms and Terminology

#33 2009-01-18 17:19:22

Re: [wiki] Textbook Terms and Terminology

#34 2009-01-18 17:50:25

Re: [wiki] Textbook Terms and Terminology

#35 2009-01-18 17:54:46

Re: [wiki] Textbook Terms and Terminology

#36 2009-01-19 00:26:18

Re: [wiki] Textbook Terms and Terminology

#37 2009-01-19 06:37:03

Re: [wiki] Textbook Terms and Terminology

#38 2009-01-19 09:18:06

Re: [wiki] Textbook Terms and Terminology

#39 2009-01-19 09:57:41

Re: [wiki] Textbook Terms and Terminology

#40 2009-01-19 11:24:14

Re: [wiki] Textbook Terms and Terminology

#41 2009-01-19 12:25:44

Re: [wiki] Textbook Terms and Terminology

#42 2009-01-19 12:26:39

Re: [wiki] Textbook Terms and Terminology

#43 2009-01-19 12:47:24

Re: [wiki] Textbook Terms and Terminology

#44 2009-01-19 13:00:36

Re: [wiki] Textbook Terms and Terminology

#45 2009-01-19 13:34:27

Re: [wiki] Textbook Terms and Terminology

Board footer