Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Re: Admin Panel Edits for 4.0.4
There’s still many instances in the panels, particularly the different Preferences panel views, where issues I brought up in the initial post still apply, namely title-style labels for non-questions type controls and question marks (where missing) for question type controls, but since I’m working on the preferences panel docs at the moment, I have a couple other notions to bring to light:
In the Preferences panel, Advanced Preferences view, Publish section:
- First widget of the Publish section reads allow_raw_php_scripting. I’m guessing that’s supposed to read as Allow raw PHP scripting? with a Yes/No radion button pair? Also, see #4 below, and then see #7.
- Three more down from that one is the ping textpattern.com? widget. What exactly is the purpose (value) of pinging textpattern.com. The internal help for that one just indicates that choosing yes lets you do it, it doesn’t explain at all why you would want to do it, or even what it does if you did. Anyone care to enlighten me?
- Five more down from that one there is the Never display email? This is awkwardly being asked in the negative (see notes in initial post), which is confusing. It should read as Always display email?, and the radio functions should be corrected if needed. Actually, I wonder if this should even be an option. The way security issues are anymore, this should just be set as no all the time and unchangable. Or am I overlooking something?
- The next two have to do with allowing PHP on pages and articles. How is that different from #1 above, Allow raw PHP scripting? Redundancy?
- A couple more down from that there is the Include email in atom feeds? widget. If a person says yes to this, is the email address open to the world/harvestable? Oh, and going back up a bit there’s another one that reads Use mail on feeds id?. Should that read as e-mail?. Also see #7 below.
- Near the end there is the Permalink title format (needs a question mark). The internal help uses the word “hypen” twice. I think it means hyphen? Also, it indicates having the option of using CamelCase. Where is the CamelCase option acted upon? Where’s the controls for it?
- The last two having to do with using plugins or pinging Ping-O-Matic make me thing this whole section of widgets needs rearranged a bit better so that like topic widgets are next to eachother. For example the admin-side plugin widget question is clear up near the top while this one is at the bottom (there’s 21 widgets in that section). Same goes for the _ping-related widgets, and so forth. It’s just easier on the brain to compare and understand like questions when the questions are directly next to eachother.
Last edited by Destry (2006-08-20 22:33:54)
Offline
Re: Admin Panel Edits for 4.0.4
To address these panel edits better, with more organization. I’ve started a new page under the Feature Requests area of TextBook for Improved Copy in Site Administration Panels. If people find things to add, please do so in this TxB page. Thanks.
Offline
#27 2006-08-22 01:52:54
- Mary
- Sock Enthusiast
- Registered: 2004-06-27
- Posts: 6,236
Re: Admin Panel Edits for 4.0.4
- Yes.
- It pings Textpattern.com (just like you could ping Pingomatic). The idea is that at some point, when we’ve got the time to set it up, we can have a “latest Textpattern-powered sites updated”.
- Yes, this is not a good one. Unfortunately, because of how the varible is used, switching the name requires updating preferences to reverse the logic. I’m not sure this would be a good idea for 4.0.4, but this can be corrected in crockery.
- This isn’t redundant. It determines whether you can enter raw PHP (
<?php echo 'hi there'; ?>) as opposed to using the Textpattern php tag (<txp:php>echo 'hi there';</txp:php>). - It is world-readable, yes. Hence the fact that it is a setting you can turn on or off (it’s an optional element in Atom feeds). And the second one should be modified, yes. This is another Atom/RSS thing. If you choose no, then your site url is used instead.
- Fixed the spelling mistake. That control is the control for CamelCase, as it states: “Permalink title-like-this (default is TitleLikeThis)”. If you pick yes, you get title-like-this. If you pick no, you get TitleLikeThis.
- It’s because of when and how controls are entered. Each pref has a sort order column, where a number is entered where it should appear in the list. Entering in one later, you’d have to update all the others’ sort ids. It’s not difficult to fix per se, it’s just a bit of a nuisance.
Offline
Re: Admin Panel Edits for 4.0.4
Thank you, Mary. This helps immensely with documentation/writing.
Some follow-ups:
2. It pings Textpattern.com (just like you could ping Pingomatic). The idea is that at some point, when we’ve got the time to set it up, we can have a “latest Textpattern-powered sites updated”.
OK, so at the moment this doesn’t work at all, correct? Can you elaborate on this “latest Textpattern-powered sites updated” concept a bit more? Where will this be located, .com?
While I’m thinking of things that are supposedly options in the admin panels but which do not work, what else in the entire Admin side is a viewable widget but which no functionality exists? Is there a list somewhere? Shouldn’t these things be hidden if they’re not functional, to eliminate confusion?
4. This isn’t redundant. It determines whether you can enter raw PHP (<?php echo ‘hi there’; ?>).
OK. Does that mean then (if chosen as yes) that raw PHP can be added to articles too, in addition to templates and forms? This is the kind of stuff that needs made expressly clear in documentation…no assumptions about what the reader already knows about programming. If there’s a FAQ that sheds light on a given subject, put a link to it from the internal help widget. Heck, Txp semantics is a stumbling block for a lot of people as it is; you start throwing in notions about using raw PHP, then help about that topic better express to what extent and where, exactly.
5. It is world-readable, yes. Hence the fact that it is a setting you can turn on or off (it’s an optional element in Atom feeds).
<strong>“Hence the fact that…”</strong> Again, I think it’s easy to assume too much about what a reader understands. The mere existence of a widget option does not always, by itself, explain the extent, value, ramifications of that widget, and it certainly should not be assumed to do so.
Making matters more complicated, a lot of the widget help copy is less than clear (saying nothing of properly structured sentences). Writing to people as if they already understand the nature of some wider scope of technology is the wrong approach, and expecting people to read between the lines for the sake of creating short help snippets is also the wrong approach, you (help writers) might as well not even bother (which, humorously enough, is the case in many instances of widget help).
Don’t take me wrong, I’m not attacking or trying to be annoying…people should know me by now. I’m simply probing these issues to improve documentation/writing efforts (such as in TextBook, or whatever) by people who care enough to make them (me for example), but to do that the extent of the functions have to be understood first, and since the internal help is failing to cut the mustard, the questions have to be asked before someone outside of a Txp programmer can fill in the blanks.
I know most of you are busy with coding and figure help is the last hurdle (it shouldn’t be), but I also know Reid is good with a pen; put that new recruit on internal Help detail, and for that matter panel-editing detail too.
As before, your feedback is very helpful and appreciated. I would encourage you from time-to-time to pop into the Site Administration docs to ensure writing efforts there reflect accurate functionality of panel widgets. I’m currently working in the Preferences docs, as you might have surmised. If any of that copy is accurate, use it to fill your Help gaps; it’s a two-way street afterall.
Last edited by Destry (2006-08-22 15:22:05)
Offline
Re: Admin Panel Edits for 4.0.4
Mary wrote:
- It pings Textpattern.com (just like you could ping Pingomatic). The idea is that at some point, when we’ve got the time to set it up, we can have a “latest Textpattern-powered sites updated”.
On a default install this should be toggled off until a use is found for it. I had to turn this off on all my sites cause it slowed down article entry.
We Love TXP . TXP Themes . TXP Tags . TXP Planet . TXP Make
Offline
#30 2006-08-22 18:17:55
- Mary
- Sock Enthusiast
- Registered: 2004-06-27
- Posts: 6,236
Re: Admin Panel Edits for 4.0.4
OK, so at the moment this doesn’t work at all, correct?
If “doesn’t work at all” means doesn’t “do” anything publicly visible at the moment, then yes.
Does that mean then (if chosen as yes) that raw PHP can be added to articles too, in addition to templates and forms?
It’s a little complicated because of old versus new behaviour (backwards compatibility). Earlier, you would insert raw PHP and it would be parsed. Later, a specific Textpattern tag was created to be used instead. Rather than completely removing the earlier behaviour, you get a warning that you should be using the tag for it instead. This new preference is a way of enforcing this – not only would you get the warning, your PHP would fail to be executed. It’s useful if you have more than one user with access to publishing articles and templates.
This is the kind of stuff that needs made expressly clear in documentation…no assumptions about what the reader already knows about programming.
There’s no doubt that some of the docs need retooling (or be created…), but no assumptions are made as to what the user’s knowledge level is. This is what the purpose of “Advanced” options is for, in part: things that are advanced, which a user may not be able to grasp. For those, usually the default is “safe” to be left alone entirely, you need not have a clue what they’re for. Those that care about such things usually do know how they work. When they don’t, or it needs clarification on certain points, that’s what the help popup is supposed to be for. And don’t forget: it’s just as easy to overdo it, and give far more words to an explanation than is helpful.
I’m not in charge of help docs, though I do have access to them. As far as I know, unlike the language definitions, the help popup docs are only accessible to the developers. I am pretty sure you need to contact Pedro to discuss adding/refining help texts.
Offline
Re: Admin Panel Edits for 4.0.4
If “doesn’t work at all” means doesn’t “do” anything publicly visible at the moment, then yes.
OK. So the chances of it being hidden until functionality is “publically visible” is nil, I reckon?
It’s a little complicated because of old versus new behaviour (backwards compatibility). Earlier, you would insert raw PHP and it would be parsed. Later, a specific Textpattern tag was created to be used instead. Rather than completely removing the earlier behaviour, you get a warning that you should be using the tag for it instead. This new preference is a way of enforcing this – not only would you get the warning, your PHP would fail to be executed. It’s useful if you have more than one user with access to publishing articles and templates.
Wonderful. So this is an evolution of functionality then, and in later relseases we should see a complete elimination of using any raw PHP (and thus the widget option along with it)?
There’s no doubt that some of the docs need retooling (or be created…), but no assumptions are made as to what the user’s knowledge level is.
My mistake. I should not have used the word “assumed”. I should have really said that Help should be written with a little more consideration to the lowest common denominator (user understanding).
This is what the purpose of “Advanced” options is for, in part: things that are advanced, which a user may not be able to grasp. For those, usually the default is “safe” to be left alone entirely, you need not have a clue what they’re for. Those that care about such things usually do know how they work. When they don’t, or it needs clarification on certain points, that’s what the help popup is supposed to be for.
Good point. And I have already made that notion clear in the wiki docs.
And don’t forget: it’s just as easy to overdo it, and give far more words to an explanation than is helpful.
This is true, though long paragraphs is not really what I was suggesting, but rather a rethinking of the more fitting words to begin with, and if it takes an extra sentence or two, that won’t hurt anything.
the help popup docs are only accessible to the developers. I am pretty sure you need to contact Pedro to discuss adding/refining help texts.
Dean once told me that it was possible for others to help write those widget help pieces, that it was managed via a cookie or something like that? Anyway, I indicated I would be interested, but I never heard back. That was quite a while ago, and at this point I would prefer to just focus on the wiki. No offense to Pedro, he’s a fine chap, but if he’s in charge of English documentation, then maybe that’s a misallocation of skillsets. Like I said before, Reid should be the one on that job (or a new, dedicated writer altogether?)
Oh, I don’t want to keep chasing two different threads that more or less deal with the same issues (documentation) so I’m going to respond to your comments below from elsewhere, here…
Mary from there: I’d recommend just Googling and placing a couple relevant links – since this isn’t Textpattern-specific, but a commonly used technique.
Actually, I think just having external links by themselves as a substitute for internal help is a bad call (equally as bad as writing 300+ words of custom copy). Certainly links to external information a nice addition that a user can choose to use, but they should not be the primary means to the end, especially if the widget is a simple Yes/No option. If there’s going to be an widget option in the admin side, and thus help copy for that widget, then there needs to be an attempt at explaining it, whether or not it’s a wider technological issue. Again, the base of my argument there was better help copy to begin with (less vague).
Last edited by Destry (2006-08-23 10:08:37)
Offline