Documentation: overview/orientation

Destry · 2019-11-24 14:47:53

jakob wrote #320239:

As part of the textpattern.tips relaunch, I had envisaged doing an article series as a step-by-step tutorial that would walk through making a very simple but typical portfolio-type site . . . I hadn’t imagined that being part of the official “docs”, or as an official theme, but rather as a walk-through for beginners on textpattern.tips

That’s a fantastic idea. The Tips site seems ideal for a multi-part series like that. Anything in the user docs should be a single document per topic, IMO.

Is this duplicating efforts already begun?

Not that I know of.

@Destry, maybe this is an opportunity for collaboration…

If I didn’t already have list of docs priorities, I’d be happy to collaborate on it. Maybe something in the future? I’d gladly give pages an editor review, though, when you’re done.

I don’t really talk about my undertakings in here, any more than necessary, because it’s out of focus and interest for most people. But for starters, I need to finish the documentation collaboration procedures and have that reviewed. As well finish up the editorial style guide, tackle the general themes creation walkthough (get the themes show on the road, you know), and various checklists tasks . Plus I’m going to look at pophelp at some point to see what can be honed and aligned better with user docs. I suspect more issues will materialize along the way.

I use the docs repo issues to manage everything, so that’s a good place to watch. I also use the Docs Team discussion board for specific writer/editor collaboration topics. That’s not public access, but it might be a place of interest for you to join. Bloke will hook you up. ;)

jakob · 2019-11-24 17:32:15

Ok, thanks for clarifying. It was that mention of the themes walkthrough that made me wonder whether we were duplicating efforts, but I couldn’t find it earlier.

Destry · 2019-11-24 17:59:48

All I’m expecting to do on that is expand a bit where the Themes panel doc falls short. Administration panel docs are meant to explain the functionality on the panels, not much more, and even themes stuff is a bit hazy for folks, I think, when it comes to hooking it up with other semantic pieces.

So the tutorial will elaborate the functionality a bit while, as phi13 put it, tie it to a ‘narrative’; something a little less abstract. Or maybe this will end up being new Themes panel doc content. I don’t know. We’re thinking about changing those pages up if it makes them more useful that way.

I certainly don’t intend to talk about building a specific site structure beyond the notion that it’s possible and what to take into account. In fact, what I have in mind might be the perfect lead to your series. We’d have these four entry points all linked up in a logical way for a theme-hunter’s journey:

docs: Themes panel (links to 2 and 4)
docs tute: Create a theme (links to 1, 3, and 4)
Tips: End-to-end portfolio tutorial (links to 1 and 4, at least)
Themes website (all the above and it’s own material)

Maybe 2 moves to 4, eventually. Don’t know. I’m still unclear what the content plan for the themes site is. Off my radar, though.

I have plenty to work on already, so if you want to do your series first, and I wait and see what it is, maybe it’s enough and I don’t have to do something different at risk of being redundant.

I’ve started some paras already, and was hoping to have in a week or so, but let me know what you think.

Last edited by Destry (2019-11-24 20:56:36)

Destry · 2019-11-25 10:39:08

In fact, I’m probably not the best person to be writing a theme tute since I’ve not really done it for the purposes of sharing one (only to hack a presentation to my needs). Several other people, however, like Phil, phiw13, Patrick, and even etc have (as witnessed by other forum threads). So if any one of you other ‘qualified’ souls, including Julian, can do that, by all means, free me of that task. ;)

WebmistressM · 2019-11-25 20:58:07

I think that it takes more than just one person to write good tutorials. I have been interested to see Text Pattern websites start to show more from the 4.8 side (the upcoming txpthemes site, and the documentation getting its update).

subscribing to this thread to follow along

Destry wrote #320251:

In fact, I’m probably not the best person to be writing a theme tute since I’ve not really done it for the purposes of sharing one (only to hack a presentation to my needs). Several other people, however, like Phil, phiw13, Patrick, and even etc have (as witnessed by other forum threads). So if any one of you other ‘qualified’ souls, including Julian, can do that, by all means, free me of that task. ;)

etc · 2019-11-26 08:49:12

WebmistressM wrote #320257:

I think that it takes more than just one person to write good tutorials.

We are rarely more than five persons to do all the work. Help welcome :-)

Destry · 2019-11-26 10:49:53

jakob wrote #320239:

As part of the textpattern.tips relaunch

Re-noticing that again.

So, that, on top of a writing a ‘series’ of articles with screenshots and all, that could take you some time. But you could say better than me.

In any case, I’ll proceed with my initial plan to write the single, low-frills walk-through doc I mentioned. I have some other items to wrap up first, but that will be added to my ticketed priorities. Maybe it appears before any glossier material and is one-step closer to themes heaven.

Destry · 2019-11-26 14:11:08

WebmistressM wrote #320257:

Text Pattern

Text Pattern 👀
🤔
Text Pattern ≠ Textpattern 🧐
Text + (p + Pattern/P) = Textpattern 🤓
Text + (p + attern) = Textpattern 😑
Text + pattern = Textpattern 😏
Textpattern = Textpattern 🤙
<txp:if_status status=“🤙”> 👍 <txp:else/> ≠👍 </txp:if_status> 😬

Destry · 2019-11-26 17:40:56

Destry wrote #320249:

docs: Themes panel (links to 2 and 4)

docs tute: Create a theme (links to 1, 3, and 4)

Tips: End-to-end portfolio tutorial (links to 1 and 4, at least)

My mind was warbling today…

It could be useful to think about 1, 2, 3, etc in terms of a single narrative, even though separate document parts. Imagine we have the following content list (a ToC) reflecting a progressive-learning series of instructions, where each piece is informative by itself for different user needs/interests. And the contents list itself (not much more) is a principle web page in the Themes site. And the site provides a main navigation link to this important page, whether it’s the homepage link, or another called ‘Instructions’, or whatever.

Introduction
Theme packages and functionality
Creating a standard theme package
Creating custom site genre package
Creating theme packages as flat-files
Porting a theme to Textpattern structure

Introduction

This could actually represent the introductory paragraph on the respective Themes website page, followed by the contents list itself. Nothing complicated or over-thought.

Here’s how to rock your own themes:

{Content list}

Theme packages and functionality

This link would be to the Themes panel page currently on my to-do list (due to some related revisions there). The page is envisioned to have two main topics:

Theme package structure
Theme creation and management

The first topic would be a conceptual overview of Textpattern themes, perhaps framing them in a couple of logical ways, using some possible terminology as it might relate with mental models people already have; a notion Bloke and I were kicking around earlier in this thread:

Standard ‘skin’ packages, being simple skinning of the default blog structure’s presentation (i.e. styles changes only, no markup changes to pages and forms)
Custom site ‘genre’ packages, involving changes to the underlying pages and forms too. I used the term site ‘genre’, suggesting a different kind of site than the default blog (e.g. portfolio, photo album, business site, whatever), but it could just as well be ‘site structure’. Whatever.

We’re talking a pretty short section here for that conceptual bit.

The second main topic/section is the detailing of the theme panel’s primary functionality for creating and importing themes, and understanding the related functionality in other back-end panels (e.g. the contextual theme menus) to make themes actually work. Again, very straight forward and concise material here.

Creating a standard theme package

This would be the other user doc on my to-do, the walkthrough. It would be a simple demonstration of the standard ‘skin’ theme package introduced in the previous doc. Skinning the default front-end; styles only, no changes to pages or forms, except possibly to add a couple more sections for expansion of the presentation possibilities.

The alternative is, perhaps, to fold this simple walkthrough into the themes panel doc as a third main section/topic, rather than have two separate documents in user docs. But I’d like to keep that thought on reserve until I see what the altogether volume of instruction turns out to be after some drafting.

Either way, the sections of the themes panel doc can serve as the links in the contents list at the Themes site level.

Creating a custom site genre (structure) package

This would be where Jakob’s advanced article(s) come(s) in at the Textpattern Tips site. As he mentioned, he’d focus on a ‘portfolio’ site, which is a site genre, and would require editing the pages and forms. A step-wise increase in tutorial complexity, as it were.

If he indeed wanted to write the piece in multiple parts, then that item in the main contents could have subitems for each series piece.

Creating theme packages as flat-files

Up to now, the different documents have been describing theme package creation using out-of-the-box functionality. But this could introduce another tutorial opportunity for someone; another walkthrough of a site genre demonstration via a flat-file installation of the Textpattern. And since Jakob is proposing to do a portfolio site, this one should be something different, perhaps a business site, or whatever.

Obviously this tutorial would want to link to yet another tutorial on setting up a flat-file installation, so there’s still another opportunity to write a needed piece.

Porting a theme to Textpattern structure

This one just crossed my mind, as I see it asked about in other threads. So, seems like yet another tutorial opportunity.

—-

By my humble reckoning, such an approach to themes docs offers this result:

Leverages writing duty (if we can get a couple more pen-lickers)
Addresses some documentation needs
Makes headway to themes site content (putting a little light in that direction); and perhaps is the only _text_-type content needed there at first, other than the prerequisite blurbs.

Food for thought only. Kick it to the dirt if it belong there.

Last edited by Destry (2019-11-26 18:32:21)

Destry · 2019-11-26 18:39:29

This poor thread got seriously hijacked. Sorry Bloke. :{

Should we move it to ‘Themes discussion’, and maybe change the title to fit. I feel like that might be safer than breaking it out as two threads.

Or just let it sit. Might miss the visibility on topic, though.

I’ve no forum power for it, in any case. (And no thanks.)

jakob · 2019-11-26 22:47:58

That looks like a pretty bold undertaking you outline there. I can’t help thinking you might be able to reduce the volume of work significantly by avoiding revisiting too much general templating ground already covered elsewhere.

As I see it, Textpattern’s themes facility

creates a formalised packaging mechanism for an organisational structure that that was already inherent to Textpattern: pages, forms and styles.
allows you to import/export packaged themes for safekeeping, transferring, sharing, etc.
allows you to install several themes alongside each other and mix and match between them for different sections (site structure parity permitting).
allows you to develop a new theme while leaving the public view unchanged.
allows you to show someone else (another logged in user) a preview of changes before they go live.
because you can link to your theme’s path, you can also include your own theme-related assets within a theme (js, webfonts, etc.). [Note: need to check they don’t get erased on exporting to disk and clearing unused forms]
(planned for later: will allow you to include plugins and theme-specific variables)
with extra plugins: allows you to work on templates, forms and css styles as flat-files with a text-editor etc. of your preference.

A couple of notes that sprung to mind from what you wrote:

Skins / themes – I suppose you could draw a distinction between skinning and theming but in my view style changing isn’t specific to theming functionality. It was always possible to make several CSS styles/files and switch them via the sections panel. I don’t know if you’d make a whole new theme just to switch a single css file, and if I’ve read the docs correctly a theme must include some basic default files so a style-only theme may not really be possible.

Flat files – There’s the aspect of exporting a theme to files and importing a theme from files, which you can do out of the box as-is. And then there’s developing themes with flat files which at present requires another plugin, e.g. etc_flat or rah_flat. People can do the former already so that mechanism is definitely worth documenting. The latter is also useful (I think) but as it requires non-core plugins, is it suitable for the “official” docs, or should it be a tip or tutorial?

Porting a theme to Textpattern structure – this almost always entails rebuilding a theme using Textpattern’s conceptual model and tags. I don’t think there’s any kind of specific correspondence between Textpattern’s theme model and that of other CMSes that one could “operationalise” into a process – apart from analysing the original theme and rebuilding in Textpattern. Perhaps that’s something one could work through in a tutorial as an example of how to set about it, but it would likely differ sometimes considerably depending on the theme or the source/CMS of the original theme. I would de-prioritise that.

Mix and match – this is something I’ve not really explored so I could be wrong here but … while I understand the principle of being able to assign page templates from different themes to your sections, it might be wise to caution against false expectations as I don’t think you can bolt together different themes and expect to end up with a uniform site experience.

As far as I understand this, for this to work well, e.g. seamlessly, the themes you switch between must share some common structural patterns and styling. If you meld together sites of completely different natures or looks, at best your sections will function fine but look totally different and at worst it may be broken (depending on how defensively the theme was built, e.g with if_plugin, if_custom_field, if_excerpt, if_article_image …).

On the other hand, where theme authors conceive their themes according to similar patterns/conventions (as is the case with some WP “theme foundries”), then this could work quite well where the site structures are not totally different.

Proposed tutorial series – having said the above, my proposed article series – what you called a genre site – would cover the general ground of structuring a template, with pages, forms and tags. It is, however, intended as a beginner’s development tutorial, picking up what Oleg said about making the patterns clear. It would assume HTML and CSS knowledge and I would not go into the hows and whys of styling (except very generally or where pertinent) but simply supply the CSS code to drop in. The idea would be that it covers two aspects: how to go about making a site with Textpattern, and how to make a theme.

I mentioned a portfolio site as it allows you to address some common Textpattern conceptual structures without getting too specialised and serves well for any kind of “collection” site, whether a designer’s portfolio, a builder’s or kitchen fitters list of references, a local what-to-see-and-do guide, a cooking recipe site, an arts and crafts site, product showcase site, book or film review site, and so on and so forth … anything with categorised collections.

I have a fairly clear idea of the intended structure already. And, as you noted, I have some other work to complete on the tips site first ;-) … and then general day-to-day work so it will not be ready in a week’s time.

Bloke · 2019-11-26 23:41:25

jakob wrote #320271:

[Themes] creates a formalised packaging mechanism for an organisational structure that that was already inherent to Textpattern: pages, forms and styles.

Exactly. We’ve always had themes, in some capacity. You’ve always been able to assign a different Page/Style to a Section.

Our notion of a Theme simply bundles up this concept into a disk-based package that is more easily shareable, and adds a few niceties like being able to test in-development layouts using live content without (too much) fear of breakage, as long as the organizational components don’t differ too wildly.

include your own theme-related assets within a theme (js, webfonts, etc.). [Note: need to check they don’t get erased on exporting to disk and clearing unused forms]

They don’t. They are kept if synchronising. Might even be kept if deleting, I can’t remember if we decided to blat everything or just the assets we understand as a Theme (Pages, Forms, Styles).

a theme must include some basic default files so a style-only theme may not really be possible.

Correct. A theme always contains at least one Page, one error Page (I think), one Stylesheet and six ‘essential’ (unquote) Forms.

while I understand the principle of being able to assign page templates from different themes to your sections, it might be wise to caution against false expectations as I don’t think you can bolt together different themes and expect to end up with a uniform site experience.

Yes, but if that’s your goal, then we’re not going to stop anyone. I’ve seen sites where the /blog is radically different to the main site – new masthead, different layout, everything. Presumably, it was either done for a reason or was amateur hour, I’m not entirely sure which.

As far as I understand this, for this to work well, e.g. seamlessly, the themes you switch between must share some common structural patterns and styling.

Not necessarily. If you’re previewing a development theme on existing content then you’ll get weird/broken results if you have a live Page template named ‘bart’ and an in-dev template named ‘homer’. At least in 4.7.x. As far as I recall, this has been relaxed in 4.8 since we now have a dedicated column for the in-dev template name per section, so in theory they can co-exist. Haven’t tested it rigorously yet.

But if you’re simply using a new theme on two different Sections, you can go nuts. Make them all have different names, different block structures, Forms, whatever. Since you (as site administrator/designer) assign a theme/page/style combo to Sections by hand – exactly as we have always done, just with the additional layer of choosing a Theme first – you are free to choose whichever ones you want.

This is of primary interest if, for example, you’re fed up of your custom-designed photoblog and like the look of Pat64’s photoblog theme on the (upcoming) themes site. You can download the zip, unpack it in your ‘/themes’ directory and import it. You can then assign it straight away to just your ‘/photoblog’ Section if you want to live dangerously. Or test it as an in-dev theme with your live photos on one or more Sections. Maybe you leave it that way and intend one day to roll it out to the rest of your site after some tweaks, but want to get the ball rolling and get feedback on it. Up to you.

On a related note, maybe a plugin could offer split-testing functionality and switch between two themes, recording which was offered for each page visit so that analytics software can analyse conversion rates (note to self/Oleg: investigate this one day and offer core helpers if required, as it should now be possible fairly easily with a plugin).

Textpattern CMS

Textpattern CMS support forum

#25 2019-11-24 14:47:53

Re: Documentation: overview/orientation

jakob wrote #320239:

#26 2019-11-24 17:32:15

Re: Documentation: overview/orientation

#27 2019-11-24 17:59:48

Re: Documentation: overview/orientation

#28 2019-11-25 10:39:08

Re: Documentation: overview/orientation

#29 2019-11-25 20:58:07

Re: Documentation: overview/orientation

Destry wrote #320251:

#30 2019-11-26 08:49:12

Re: Documentation: overview/orientation

WebmistressM wrote #320257:

#31 2019-11-26 10:49:53

Re: Documentation: overview/orientation

jakob wrote #320239:

#32 2019-11-26 14:11:08

Re: Documentation: overview/orientation

WebmistressM wrote #320257:

#33 2019-11-26 17:40:56

Re: Documentation: overview/orientation

Destry wrote #320249:

Introduction

Theme packages and functionality

Creating a standard theme package

Creating a custom site genre (structure) package

Creating theme packages as flat-files

Porting a theme to Textpattern structure

#34 2019-11-26 18:39:29

Re: Documentation: overview/orientation

#35 2019-11-26 22:47:58

Re: Documentation: overview/orientation

#36 2019-11-26 23:41:25

Re: Documentation: overview/orientation

jakob wrote #320271:

Board footer