Open wion opened 4 years ago
Bloke
commented
4 years ago Incidentally, if GitHub's Jekyll implementation supports it, note that the include syntax permits passing parameters that can be injected from the calling location.
Thus we don't (necessarily) need to make the included doc generic, as we may be able to pass in some content that gets replaced inside a placeholder or two, to make it specific to the doc in which it's included.
wion
commented
4 years ago That's interesting and good to experiment on with respect to includes. In this case, I don't think we need to have the secondary functionality repeated in a panel doc, even if it is single-sourced. Once people learn what those features are, it's like riding a bicycle. They don't have to keep wading through the same instruction in every page. Make sense?
wion
commented
4 years ago In any case, if we do later decide to single source these bits, we'll have a single vetted page to build includes from. We could even build the sole page with includes just to experiment there and take it one step further. First step, though, is to get the multiplicity edited out of the panel docs. This might be the sensible way to it.
Bloke
commented
4 years ago Yeah, now the interesting thing is that I'm not sure on the split here.
With things like "Logging in to Textpattern" you certainly don't want to include the entire file verbatim every time it's used. You want to link to it because, as you say, wading through it on every page is going to be tedious. Same with prefs when you reference them in a doc, you don't necessarily want them to have the whole content shown, just link to it.
However, on the Admin/Preferences page, we do want to include the content of each individual file. And this is where I'm not sure how flexible Jekyll is. We want both:
_includes directory - remains to be seen).I'm not sure if those goals are mutually exclusive. If a fragment has no Jekyll frontmatter, it cannot appear as a standalone link as it cannot be shown to users independently, which we want when linking to them.
But if it does contain frontmatter, it could become navigable (I think) out of context, which we probably don't want.
If we have freedom to control how and when these fragments are included and linked, then there's no harm in simply not using the 'include' concept but just keeping the fragments squirelled away in a directory as you suggest, and only linking to them from other places.
The only impact linking has (vs. including, which renders the content of the file) is on the Preferences panel description itself. Instead of seeing them all on the page, we'd have to construct - essentially - a page that acts as a TOC:
Intro text blah blah...
That's extra navigation burden on the reader as they need to click a pref to read about it and then click back to get to another one. But it does keep the page weight down :)
wion
commented
4 years ago You're definitely thinking way ahead of me on it. For now I'm just focused on this issue. ;)
I just committed the page for this issue. Have a look at it... https://docs.textpattern.com/administration/common-panel-functionality
And here's the revised opening to the Themes panel doc I'm currently working on, showing the note in proper context that bridges the panel doc with the secondary help material, if anyone needs it...
Themes panel
The Themes panel is where you create new themes, import themes from an uploaded folder, and manage or edit themes you have collected. From the perspective of a fresh install of Textpattern,[^demo] this document details the panel’s primary features,[^common] and the related controls in other panels. You may also see Creating a custom theme for an end-to-end tutorial on doing so, which refers back to this page when describing panel functionality. And be aware that themes functionality is still evolving. An upcoming software release will integrate preferences and plugins, for example.
On this page:
- Table of contents {:toc}
[^demo]: Use the Textpattern demos for reference if you don’t have a fresh install handy. Copy the provided username/password, then follow the ‘Admin’ link in the Production demo options.
[^common]: Explanations for common (secondary) panel controls like search, list handling, and pagination are detailed in Common panel functionality.)
Is this making any sense for immediate objectives? I think the notes approach is clean and should work fine.
wion
commented
4 years ago Er, actually, now I just committed the page.
wion
commented
4 years ago If anyone sees where this fails, falls short-sited, or could be improved in any small way, I'm happy to revise. Otherwise I'll close and move on to the next.
wion
commented
4 years ago One thing I noticed while editing this, was the necessary use of (and subsequent necessary clarification of) 'list' and 'table', two semantically different things, to talk about the 'lists'/tables in panel main displays. Secondary features, like List options use the 'list' angle too, but at the same time it's necessary use 'column' or 'headers' when talking about sorting and toggling, and whatnot which are definitively table constructs.
So this is one of those things that ideally should be addressed at the root, at the interface strings, under a decision to use one line of terminology or the other.
To me it's a table, clearly, and to anybody, so table, columns, rows, cells, column headers... these are the terms to be using in strings, docs, and wherever. I realize the concept is, using a type for example, a list of themes, but I don't think it confuses anybody by saying 'the themes table', especially when in context of the panel.
Should this be a ticket in the software repo?
Bloke
commented
4 years ago Yes, good point. We have named them 'list' options in the code too, but you're right, the string should probably be 'Column options' or something along those lines. Please raise a ticket in the Textpack repo.
wion
commented
4 years ago Will do.
wion
commented
4 years ago This page likely needs reconsidered for relevancy in the new architecture. Our focus should be on the specific functionality unique to a given panel, not on general/obvious functionality common to many panels. So while it was a good first step to remove this to a single doc, it might be appropriate to just remove it entirely, in fact. But let's wait and see where things are at when the new architecture and docs are finally in place.
Bloke
commented
4 years ago I kind of like the idea of this page still. Even if it's just for explaining things like:
Everything else, such as upload boxes and textareas, are specific to particular panels.
The only issue with describing this in generic terms is that the headings and options are different so we just need to be careful it's applicable to all and there's no specific info. I don't think making this an include and passing in params is going to be worthwhile. A single link to this doc from any place it might be needed when describing how to do specific workflow stuff is probably fine.
But if it's deemed superfluous and obvious in the UI and doesn't need explaining, that's also fine.
wion
commented
4 years ago Okay.
I've never been much of a selection controls user, except to delete things. ;) But after working on the themes doc, which has the new functionality between themes and sections panels, I've been paying closer attention to it and how it can change context across panels.
I think the way to handle common controls like that but which change in different locations for different tasks, is to simply describe the specific control options in the course of the doc that describes a given task. The themes doc being a good example, or at least when I'm done with it.
Once you do that for all the main kinds of tasks, that even need to be explained beyond the obvious, you're left with, what... This page, I guess.
https://docs.textpattern.com/build/common-panel-functionality
What
A single page that details all the secondary functionality common across many panels, like search, table sorting, pagination, table record(s) handling, and whatnot.
Why
This information is unnecessarily repeated in panel docs, with only a few words difference each time to specify what panel item/template is in context.
We could easily write it once in less specific terms, and thereafter point to the page as a note in the initial intro/overview matter of a given panel doc, should anyone even need the reference. It's intuitive functionality that doesn't need repeated, that's for sure. I don't think it needs embedded via content includes either. It just needs written once, put to the side, and linked to from panel docs where relevant.
This sharpens the focus of panel docs to only the primary features/functionality, as it should be. This also offers and opportunity to break from the long-standing habit of writing panel docs as simple records of what users can already see. From hereon we can revise panel docs as a balance between detailing the primary interface functionality and elaborating a bit on the nuances and goals of using it. Not as tutorials, exactly, as those should still be separate stories around specific goals and using specific examples.
I am somewhat doing this for the Themes panel that I'm revising in relation to writing a themes creation tutorial. It has some nice secondary descriptions we can use as material in the proposed page. We can then look at these themes docs when I'm done and discuss if these ideas as described are on the right track there, and perhaps identify how things might be nudged more to make panel docs more useful than tree filler.
Then we can feel-free to tackle other panel docs, starting with at least the removal of secondary feature descriptions and sharpening focus.