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.

Destry · 2020-01-05 09:47:00

I was just being facetious. My point being, it’s never about the platform or the format. It’s always about humans never wanting to write/maintain documentation. Whether it’s word-processed or tediously marked up with HTML makes no difference in the end. One is as good as the other.

But, I’d say what would work in your case is a URL-less section — e.g. /docs. If that lands, then there’s no additional back-end functionality needed. Write the docs like Txp articles and read them via the View or Preview features from the Write panel.

phiw13 · 2020-01-05 09:58:19

Destry wrote #320841:

But, I’d say what would work in your case is a URL-less section — e.g. /docs. If that lands, then there’s no additional back-end functionality needed. Write the docs like Txp articles and read them via the View or Preview features from the Write panel.

Nope, that may work for a (smallish) site with few or only one participant. I noted upthread how I used the original ID=1 welcome article as an ersatz for this. It only sort of work on a very good day. The lady often and regularly forgets how to view (view link) or access (search the article by date/ id in the backend).

A dedicated menu item as suggested by Colak has a much greater chance of being accessed.

Your point about writing an maintaining the documentation is of course completely correct.

jakob · 2020-01-05 11:53:59

I’ve tried both PDF and html variants:

PDF: some clients like to have a printout to refer to, so a PDF with 1-page per topic and a cover “contents-page” is perfect for them.
Help section: For the few multi-author sites I’ve done, I just made a separate textpattern section that didn’t appear in the menu or feed and linked to it from the dashboard in the admin area.

The lady often and regularly forgets how to view (view link) or access (search the article by date/ id in the backend).

For me the obvious solution for users who edit infrequently and forget their way around the admin area is a dashboard. Set that as the start page in Admin › Settings and it’s the first thing they see on logging in. You can give them pointers to what they can do, how they can reach what they were last editing, and you can point to your article ID# directory … or output it’s contents in your dashboard.

Here’s some outline code for a very simple dashboard that you can use in conjunction with smd_tabber or similar. I’ve dumbed it down from an own dashboard and used phil’s hive styles so this should give you a welcome message across the top followed by three columns with options and recent articles. You can spruce this up, add things like recent comments, your moderation queue, site stats, links to template articles to use as starting points or add a big “Let me just write…” button to skip the dashboard.

<div class="txp-layout  welcome-dashboard">

    <div class="txp-layout-1col">
        <h1>Welcome to <txp:site_name /></h1>
    </div>

    <div class="txp-layout-4col">
        <p>Welcome to the Admin area. Here you can write and edit articles, enter new projects, check for new comments or post suggestions and upload files and images.</p>

        <h3>Need help?</h3>
        <p>See the <a href="/link-to-your-helf-file">quick start reference</a>.</p>
        <p>If you have any problems or questions <a href="mailto:admin“@site.com>send the admin a quick email</a>.</p>
    </div>

    <div class="txp-layout-4col">
        <h3>What would you like to do?</h3>
        <ul id="welcome_options">
            <li class="article"><a href="?event=article">Write a new article</a></li>
            <li class="list"><a href="?event=list">See the existing articles</a></li>
            <li class="image"><a href="?event=image">Upload an image</a></li>
            <li class="file"><a href="?event=file">Upload a file</a></li>
            <li class="password"><a href="?event=admin">Change my password</a></li>
        </ul>
    </div>

    <div class="txp-layout-4col">
        <h3>Recent articles:</h3>
        <txp:article_custom limit="5" wraptag="ul" break="li">
            <a href="?event=article&step=edit&ID=<txp:article_id />"><txp:title /></a>
        </txp:article_custom>
        <p><txp:article_custom limit="9999" pageby="1" pgonly /> articles in total. <a href="?event=list">&rsaquo; see all</a></p>
    </div>

</div>

You can go crazy and style this all nicely, add icons, etc.

BTW: I have this topic on my list of txptips to write (but it won’t happen right away).

@Phil: BTW, could we perhaps have a .txp-layout-3col in the hive patterns? On my own site, I’ve used your 4col and added style="width:33%" to override it.

Textpattern CMS

Textpattern CMS support forum

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