search

textpattern / textpattern.github.io

Textpattern CMS user documentation.
https://docs.textpattern.com
GNU General Public License v2.0
15 stars 17 forks source link

proposed: Building site structures #152

Open wion opened 4 years ago

wion commented 4 years ago

Proposed title and location of new page... https://docs.textpattern.com/build/site-structures

Situation/Scenario for proposal

A single doc that returns to a holistic discussion of building website structures in terms of semantic building blocks

Value

Folds in the panel docs pages for sections, pages, and forms. Ties with concepts discussed in context of themes doc.

Resources to consider for draft

Add information text and link

Bloke commented 4 years ago

I know people have tried to draw the relationship between our objects before, to varying degrees of success. Trying to cram things into a single small image is tough, but I think some sort of infographic would be a good way to visualize the semantic model. It can work down the page that way, introducing topics as we go.

To that end, as a bare bones sort of idea, I've thrown together this:

TxpSemanticModel01

There are still gaps and it's not pretty and needs whizzy graphics/drawings and all stuff I don't have the artistic chops to create. But I wonder if it could be used as a basis for coming up with something that visually walks people through the basics. Something we could either put up wholesale or chop up and sprinkle throughout a document that talks about the architecture.

Things we need to really try and hammer home - which I haven't done here - is how you can use a single page/style for multiple sections. I've lined stuff up beneath the sections to show how this might work, but we could do with some dotted lines or guides extending from the sections down into the Theme box to show this more clearly.

Also, maybe better tag examples could be used to show conditional/container and singles.

It's also missing the 'default' page for the homepage because I ran out of space in the Themes box. Need to shehorn that in somehow.

I was approaching it from a fictitious site perspective so you can see the sections, the articles with their two types of 'context' shown (it might be nice to link that to the tags at the bottom somehow, but not essential), and the pages/forms/styles and how they go to make up the various content that you might see in each section. I show forms being injected into pages and also included an example of a form calling a form to show nesting.

Also, I put the database and filesystem at the bottom to show that's where the tags are fed from, and that images and files are not stored in the database. Could add a few arrows here if we cared. I didn't mention themes on the filesystem as it adds complexity that's not necessary in this view, imo.

I'm sure it could be laid out better and jazzed up, but I wanted to capture as many of the base elements as possible and then throw it at someone else to see if it could be improved. If anybody wants the Photoshop file - all 8MB of it - then holler and I'll share it via WeTransfer or something.

Worth pursuing or not bother?

wion commented 4 years ago

I think it's a great idea. Could even be a separate thing, depending how graphic you want to make it. I can fumble my way through a graphics app, but I admittedly don't have the knack or graphic design eye for producing big files that scale well (i.e. can still be read when not poster size), and that's critical for infographics.

Another idea, and I've always wanted to build one of these but it would probably take @philwareham's front-end skeelz, and I'm not even sure what they are called, but they used to appear here and there about a decade ago, mainly as design experiments, but they were always really cool. Basically it was a play on the endless-scroll idea, but you had a motion story playing out as you continued down. It worked really well for animating infographics without any user input but scrolling. The only one I can still find is not really an infographic, but it still shows the concept really well. Ben the Bodyguard. Scroll and enjoy.

They don't have to be this graphics heavy, but this one was more narrative so it fit well. All the others I've seen were more flat-design, infographics related, and it was still pretty slick and effective. You can have things sliding in from the side, piecing together, info boxes to read, and so on. All along a neat timeline and conceptual space line, as you scroll. And if you miss something, scroll back up and see it again.

That would take a lot of time and work, though; resources not readily available for anyone, most likely. That's probably why there were never a lot of them. Labour-intensive.

wion commented 4 years ago

The next best thing is probably parse the graphic into more digestible images and work them into the article that way, as you were saying. More control over text that way. Will get done faster. Just as effective. In fact, it makes more sense all things considered. ;)

Bloke commented 4 years ago

Yeah. Using the height was the sort of thing I was after. Breaking it into chunks so everything was still readable, revealing each bit and how it relates to the part above as you scroll. Or weaved between text as you work down the page.

An unfolding narrative using skrollr is nice but it's a lot of work and a pig to maintain. Trust me, I've tried it. It's fine for things that don't change much.

My favourite example, although it works better on desktop, is the walking dead promo. Amazing.

Breaking the idea up into smaller images also works. If anyone's a dab hand with a pencil, sketch some ideas and scan it in so we can figure something out.

wion commented 4 years ago

Breaking it into chunks so everything was still readable . . . weaved between text as you work down the page.

This seems doable, right on a doc page, even if by separate files.

Things are getting tight now with the holidays and all, but I can maybe give it more thinking in the new year. Pencil sketches I can do, if needed.

I'd suggest getting the main ideas written into draft, start structuring the document that way first, then come back and re-map it with images later. That way a page is at least started and working; progress can be made toward the architecture clean up.

I've never seen a horizontal scroll like that before. Really well done.

Bloke commented 4 years ago

Shall I have a go at throwing some words down then? Just curate some useful bits and pieces from the various Presentation panels and bind it together.

Do you think it'll be more digestible if we approach it from the view of creating a standard website? e.g. create sections for content (that can briefly mention articles and categories), which gets people thinking about site structure and which pages share the same look and feel. That drives page templates and stylesheets. Then fold in discussion about how to break things up for maximum reuse (forms). And at the end, mention themes and link to the themes doc as further reading, because that takes the concept further by having parallel sets of pages/forms/styles.

In essence, doing a sort of worked example walk-through instead of trying to make it an abstract concept.

wion commented 4 years ago

By all means, have a go. Pull out from the panel pages what you think is worthwhile (avoiding needless explanations of panel functionality) so that when the doc is drafted, we can point to it and finally remove those 'presentation' panel docs.

So I imagine a doc will have an initial main section that introduces the presentation assets/templates: just simple descriptions like I did in the themes doc. I called them 'assets' there because they're all part of the themes package. But in this case I'd use more specificity since this is the root doc where they are being defined, as it were. I don't think shoehorning them all as 'templates' works. For example, I've never considered CSS styles as a template file. Nor do I really think of markup chunks (a kind of content component) as a template either; it's actual content to go in a template. Pages, yes. But you see what I mean; use terms that anyone understands by simple web convention.

Note that Phil had links in tag pages that pointed to 'Page templates explained' and 'Form templates explained'. Those links need to be changed so they point to whatever respective sections above: 'Page templates' and 'Form content; so they really need to be considered and stuck to from that point on. Or don't link out from the tag pages like that. Maybe there is some includes usage to be had here. Don't know.

None of that yet worries about graphics, but the next section does. Here is where we start folding in concepts from your chart. I worked with the idea of the default structure in the theme doc. I think that's always a smart place to start because it gives people a tangible example to investigate, and the docs are supposed to be about the system out-of-box. But where I used back-end, naturally, here we can use front-end perspective, and instead of making up graphics, we can simply use actual screen shots of the default front-end.

I'm looking at your graphic and there is /blog, right in the menu. Perfect. So I'd start with a very simple walk-through of your chart using the /blog section as first doc section example. So we add this kind of idea and fold in relevant images or code examples in each section. This will make a nice cross-reference with the themes doc.

'Blog structure' will be introductory text of the default theme, a good place to link to the theme doc.

'Default Textpattern assembly' is where you finally start introducing the act of putting things together. Here is a good place for the green block section of your chart, but re-done to focus on the context of the blog specifically.

'Forms as content' is a closer inspection of how forms are used in relation to pages; again, in blog context. I would not explain every form, but maybe one to lay out the concepts. And give links to the default forms in the repo rather than duplicate the content here as needless code blocks.

'Tag power', or whatever, is where the notion of tags as markup/content in form chucks or in page templates comes in. Again, don't go into too much detail, but use a form and/or part of a page template to help demonstrate/explain the idea.

Then we have one more main section in this document. A differ structure type. Take your pick. A portfolio might be nice because it focuses on images. People like images. The idea is to follow the concepts laid out in the blog, this time doing new assembly for the portfolio. Here you can be more detailed in each section because you're explaining something that doesn't already exist.

That's what I originally had in mind, and I think it matches pretty well with your graphics ideas, if not all of them.

We can adjust from there. Make sense?

wion commented 4 years ago

That structure is just to show what I had in mind. But you might have another angle that's perfectly fine. Go with it.

Bloke commented 4 years ago

Winner. I'll see what I can fashion.