How to for writers

colak · 2020-01-02 21:53:31

A feature request although it will not be much use to me and many of us here. After responding to the post here I felt that there was one thing which we may need in order to help those who have sites and those who inherit them, whose knowledge or access to the interface may be insufficient.

When installing txp we get an article containing the basics. These basics of course can become slightly more complex for many sites.

There have been many times that we are helping people here who, for whatever reason, do not know some of the intricacies, their designers introduced. It would be prudent if txp came with a back-end help document which can be filled by the designers and contain particular instructions detailing their proposed methods for the creation of, and specifications for, the production of content under their particular design. This could be accessed via a link (?) from the menu, activated after the creation of this document, or it could contain the initial content of what we have today as article 1.

It could have an interface similar to that of the write tab but without any side menus. This form could support textile but its styling should follow the specs set by Phil.

I know that adi_notes can do this more efficiently but as some site owners do not update txp until it is almost too late, this could be a core element which we will be able to more or less guarantee its compatibility in the future of the cms but also help those who may inherit the design as by reading it, they will be able to understand rather than decode the initial designer’s instructions to their clients.

jakob · 2020-01-03 20:33:57

While I’m less sure whether this need be built into txp from the get-go, the use of a notes panel or even just a dashboard panel with instructions is a good idea.

I saw when I updated the site you mentioned that the original designer had included image sizing details in the image category title (e.g. “Gallery thumbnails at 200×200px”), which is an approach I’d not thought of. On the image front, the (forthcoming?) inclusion of more thumbnail sizes à la smd_thumbnail might make this specific aspect less of an issue, as you are likely to have correctly-sized images. Servers are now also more powerful and less prone to running out of memory when processing larger camera images (though I haven’t tried chucking the kind of high-megapixel images that newer cameras produce at it).

My own approach varies. Where the site owner is savvy and willing enough to update their site on their own, I definitely encourage that: not only does it free up my own time for other work, it also empowers them to take control and guide their own site, which is always a good recipe for a successful site. For some people this is something they naturally expect, but for others it can be something they feel they need to overcome or master.

For many people, a dashboard panel (e.g. using smd_tabber or similar) helps. I really like the “just write” approach of Textpattern, but sometimes it is more helpful to provide new users with quicklinks to certain actions they can do next, a list of the most recent articles, the most recent comments (if they are using them) etc. It can end with some quick reference details such as image sizes, what categories or override forms to use, what details to put in custom fields… That last aspect can – since txp 4.7 (I think) – be provided in the form of “instruction text” for custom fields that appears as a “hint” beneath the field label. You can edit that with glz_custom_fields (v2+) or enter your own label hints in the textpack field under Admin › Languages. It’s not very long but is great for things like reminding users of the date format to use, e.g. YYYY-MM-DD.

For a few larger sites, I have made small instruction PDFs for common editing actions i.e. not how to use txp, but how to do the things they will want to do. I try and keep them step by step with one action on one page. I place a link to that on the dashboard so it’s always available in a separate tab. It is, however, quite a lot of work to produce.

EDIT: I found I had a pic of one already on the German language forum here. That thread also mentions bot_admin_tooltip as another possible “onboarding” tool.

colak · 2020-01-03 21:39:36

That was a very interesting discussion which I totally missed, when it was happening almost 10 years ago. I used g-translate which I unfortunately think that it did a great job:)

I agree with you with all that you wrote but I think that just having a textile-enabled form could actually achieve that. Admittedly though, multi page instructions could be clearer for clients. An easy way could be that the form could also have a title field and in the case of multi-page documents, those titles are linked and shown in an <aside /> or other more semantically correct tag.

I very much respect the work you put for the pdfs, but like paper, e-docs, as you may have experienced, do not always get passed on.

ps. I looked at your solution which I will test this weekend as it is getting very late here.

bici · 2020-01-03 21:47:19

i encourage exploring an option to have “Instructions/Notes “ added.

On EEcms i have this option on all fields:

Instructions
Field instructions that appear in the publish form.

I add notes instructions that pertain to those fields that might need further information: eg. All images must be size 420×420 etc.

Bloke · 2020-01-04 00:18:48

bici wrote #320807:

On EEcms i have this option on all fields: Instructions Field instructions that appear in the publish form.

As jakob says, we have that in Txp, but it’s not in the UI. It’s available via textpack so you can target pretty much any admin-side field and add a short description to it. Core will render the string.

If you want to play with this feature:

Install smd_babel so you can easily add/edit your own strings in any language.
From the plugin’s Admin tab, choose the panel you wish to affect from the dropdown selector (e.g. ‘article’ for the Write panel).
Add a new string called ‘instructions_<name-of-the-field-in-HTML>’ (e.g. instructions_title for the Title field, instructions_body for the Body field, instructions_status for the Status dropdown, etc) and provide a string translation.
Refresh the Write panel and your text will appear just above the field control.

bici · 2020-01-04 03:40:17

Bloke wrote #320809:

As jakob says, we have that in Txp, but it’s not in the UI.

Thanks for the tip, butI would prefer that it be baked in as default.

i try to stay clear of plugins, as much as possible.

phiw13 · 2020-01-04 08:46:37

For one client, I’ve re-used the original id=1 welcome article to both give her a style guide and some explanation on the structure and building blocks, the pages and forms in use. The article is set to hidden etc. That is not ideal but for basically a one person operation it actually works (in her, admittedly not-so-complicated case).

oh, and id=1 is actually easy to find when sorting by ID (or date).

Bloke wrote #320809:

As jakob says, we have that in Txp, but it’s not in the UI. It’s available via textpack so you can target pretty much any admin-side field and add a short description to it. Core will render the string.

Thanks for the tip on using smd_babel for adding a tip/instruction. Still a bit limited to a short sentence kind of thing, but useful nevertheless especially for the various fields in the side column of the Write panel.

Bloke · 2020-01-04 09:06:35

@bici: the plugin isn’t to enable the feature. It’s baked into core. The plugin is just a simple way to create and manage your strings. Delete the plugin after you’ve created the db strings and it’ll still work. Or, if you prefer the hassle, make the changes to the txp_lang table directly in SQL.

Bloke · 2020-01-04 09:12:53

phiw13 wrote #320815:

For one client, I’ve re-used the original id=1 welcome article to both give her a style guide and some explanation on the structure and building blocks.

Yeah, I’ve done this too for some people.

[instructions are] still a bit limited to a short sentence kind of thing, but useful nevertheless

Well, yeah. You could go nuts here, but the UX might suffer! We’ve still got to figure out how to manage custom pophelp better so you can balance “field tips” with “full help”.

Destry · 2020-01-04 17:34:04

Last I looked out from under my rock, providers (designers or any other type) provided a written document, usually in Word or PDF format, specifically for a given client about how the statement of work was met, plus instructions for employing the web app. Anything less was not a sufficient record of delivery.

Drop that into the Files panel. Job done.

An interesting idea, though, would be a popup file reader. Kind of like the popup Write editor viewer thing, but for reading PDFs (at least).

Last edited by Destry (2020-01-04 18:00:06)

bici · 2020-01-04 17:54:46

Bloke wrote #320816:

@bici: the plugin isn’t to enable the feature. It’s baked into core. The plugin is just a simple way to create and manage your strings. Delete the plugin after you’ve created the db strings and it’ll still work. Or, if you prefer the hassle, make the changes to the txp_lang table directly in SQL.

thanks for the clarification! I am now in the midst in using it for a friend’s site. she needs hand-holding and this will do the trick.

colak · 2020-01-05 08:32:45

Destry wrote #320824:

Last I looked out from under my rock, providers (designers or any other type) provided a written document, usually in Word or PDF format, specifically for a given client about how the statement of work was met, plus instructions for employing the web app. Anything less was not a sufficient record of delivery.

Drop that into the Files panel. Job done.

An interesting idea, though, would be a popup file reader. Kind of like the popup Write editor viewer thing, but for reading PDFs (at least).

I still believe that pdfs might not be the most sustainable method. Consider larger sites, which are getting a redesign every so many years (ie. http://seidler.net.au/). These redesigns will of course need new instructions to the clients.

With textile, designers will be able to add images (maybe called from a specific directory outside the txp structure, accessible by writers, in order to guarantee their presence) but also content the complete, textile toolset can provide.

By having this part of the core, as opposed to as per the designer, it will be able to work on any device. I envision it to have a very simple interface for designers. A title field and a body field. The client end could be a back-end rendered presentation which can consist of the title, body and a sidebar with automatically generated links to the other pages. The default sorting could be posted asc which could also be changed to Title (with titles starting with 01, 02, etc) for those designers who do not like to write linearly.

I also think that these instructions should take all the space under the txp back-end menu rather than using lightboxes or any other method. I believe that plain html rendered, clean documents would cover all cases.

The only thing clients will need to know is how to access the back-side, their login, password, and to click on the ? link from the menu. From there on, it will be up to the skills of each designer when they write their instructions.

Textpattern CMS

Textpattern CMS support forum

#1 2020-01-02 21:53:31