Referencing prefs panels and style guide implications

[wion]

You may have seen my proposal for changing the header/names on tertiary pref panels. Whether or not that happens (it would be good), I'm going to make it style guide rule to refer to the panels in docs as:

• Basic preferences
• Advanced preferences
• Language preferences

In other words, those would be the link labels and bold, for example:

"**Basic preferences**":url

As the style guide will make clear for UI content, titles and headers should be bold, so that's why you need bold on the links too, for consistent formatting. I was originally putting the bold marks around the entire link (e.g., **"Basic preferences":url**), but that was uglier. First way is better, I think.

I'm also going to change the file names for those doc pages, because the poor naming of those panels was screwing me up there too. So now they'll be:

• basic-preferences-panel
• advanced-preferences-panel
• language-preferences-panel

Question: Is there a trick for find/replace across the entire docs repo, or even within a given directory?

[Bloke]

Bear in mind that from 4.6.0, Languages has its own dedicated panel (under 'Admin') and the Prefs panel (at present at least) is just a single panel with twisty groups for each area. No more advanced / basic distinction.

[philwareham]

I want to base this documentation on v4.6 so any reference to 'advanced' and 'basic' preferences needs to be removed from articles.

[wion]

Ah. Wasn't aware of the changes. Yeah, future proofing is the direction to focus on docs, for sure. So it's just Preferences panel and Languages panel, then. Yeah? That's great. I'll re-tool the doc pages that way.

[philwareham]

Cheers!

[wion]

I guess it's time to install a local 4.6 branch. Is that were i might see headway on these changes?

[philwareham]

Yep, might even be worth installing one from the 4.6 master branch, one from the 4.6 admin-layout-update branch. They will eventually merge at some beautiful point in the future.

[Bloke]

Absolutely. Get that sucker cloned! You might also want to hop to the admin-layout-update branch too, as that's what is going to become the new interface (at least for Hive). Edit: Phil beat me to it, though he seems to have two repos, one for each branch. I'm running a single repo and git checkout <branch name> to jump between them. Either works and have relative upsides and downsides. A single repo is most notably affected at git pull time where you have to remember to pull the master branch last or else you get an extra commit (or sometimes have to merge by hand, which is painful).

btw, I'm assuming that the docs are refraining from mentioning position-based things like "the Sort/Display area on the right" because that position may differ from admin-side theme to theme, right?

[wion]

Docs should be written from the perspective of what the default presentation will be. So if that's Hive, then it's Hive presentation. That said, we should avoid detailing where things are and focus on what they're called, so if the labeling is consistent, it shouldn't matter, whether it's a different theme or layout on a phone screen (ideally speaking). And that's why a style guide is so important too, about how to refer and format references to UI elements.

So, I'll install the admin-layout-update branch, because if Hive will be the default, then that's the initial perspective.

[wion]

Is it feasible to clone the admin-layout-update and run a local site that way so I'm always just updating my local files? Or better to use the zip download?

[philwareham]

Yes, that's what I do:

• Clone the repo.
• Install Textpattern locally as you usually would (for me it's via MAMP).
• If you want to test a different branch, just switch to it in the GitHub.app. Since the config.php file is ignored between branches you can flip between them without damaging the install.

[wion]

Thanks. Didn't realize that about config.php. Nice!

[wion]

Okay, local 4.6 future is live. ;) Thanks for the help.

Just so I have a reminder somewhere, this is what I'm doing for preferences, using these files:

• preferences-panel.textile
• languages-panel.textile

I'll merge the Basic and Advanced content in the "preferences" file, and it will have a "Basic" and "Advanced" sections until 4.6 is released. Then edit the file again to adjust for 4.6 once that's released. That should work fine.

I just need to fix a few link paths and labels at this point.

[wion]

@Bloke had said:

btw, I'm assuming that the docs are refraining from mentioning position-based things like "the Sort/Display area on the right" because that position may differ from admin-side theme to theme, right?

Yeah, as mentioned, we should only need to pinpoint elements by their UI names, not locations. I'm just coming back to this because I happened upon a good example, I think. This is from the main plugin development doc:

Consider this example, which adds a radio button to the existing button series in the Write panel’s Status widget. ...

Is that on the right track? That should satisfy any admin theme or device size situation. It's up to the reader to find the element based on page link and element name, which is all they need.

[philwareham]

Yeah, in that example the write status widget has a select menu in v4.6 not radio buttons, so it would need to be changed to something like...

Consider this example, which adds an additional entry to the existing series in the Write panel’s Status widget. ...

[wion]

Sure, we'll need to normalize the descriptions to the version. But that raises an important question: How long until 4.6 is released? Because if it's going to be another year, or even six months, then it's not a good idea to write docs for a 4.6 UI -- not to that level, anyway. We can talk about Prefs and Langs panels, like shown in the tree here now, but the specific elements should still be described as users will see them or it's getting too abstract.

[philwareham]

Closing this, as (mostly) documentation has been rewritten for Textpattern 4.6 UI onwards.