Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
Pages: 1
User docs changes
Just a heads up that we (docs whisperers) have been busy with a slight reorientation of the user docs, and if you follow the docs repo issues at all, you’ll have noticed. The motive is to make user docs more useful than just a tags reference, while at the same time make docs editorial more efficient (i.e. less overhead for the skeleton crew of volunteers).
The bulk of the action, or at least the initial idea that necessarily stretched a bit, centers around a re-write of the installation and administration stuff. For example, all the panel pages have been pretty useless for a while and especially since pophelp was introduced. We’re eliminating panel pages and dry documentation of UI thing 1, thing 2, etc, in favor of writing fewer but more focused (and sometimes lengthier) concept-oriented and task-oriented pieces.
This also required looking at the architecture of the docs tree, and most of it needed tweaking in some way: in light of the re-writing, better organization of tags material, and in adopting things like includes for single-sourcing common lists and using root-level relative links. The restructuring is now mostly done and reflected in this new homepage in development, index2.
Don’t bother bookmarking that link, it will be gone in the near future, perhaps anytime. What you see there will replace the normal homepage. But it shows you some things: First, we’re simplifying to just three main regions of documentation: setup (installing and configuring), build (construction and presentation), and, of course, tags (tags and attributes). Unlike in the current docs homepage, all existing documentation will be listed and directly accessible via the new homepage, no more having to drill in to find a doc (e.g. the useless panel docs, or that odd piece that links to something else). The exception, of course, being tag pages, and their category pages, because of the large volume. Otherwise, what you see listed on the homepage is what is in the tree. Once we get those cued docs produced, it opens the door for more topic-oriented pieces, if we need them. Editors will decide what those will be from the kinds of problems we see brought up in the boards. Audience and scope remains being new administrators and core functionality.
I would bring your attention to the tags, and specifically this link to the Tags index (reference) and underlying tag pages. That is the new permanent link to the ‘reference’ (index)! Everything is working. The old links will be gone ASAP. Update your bookmarks accordingly. Unfortunately, GitHub website are limited somehow with respect to redirects. One of the others can explain that to you if necessary. I just deal with the words. But this will smooth out pretty quickly if everyone does their part to help re-link the entry point. Yes, the adjustment was needed because all the tag pages were not isolated to their own directory, as should have been done originally, making it somewhat complicated for maintaining a flat-file system. But we recognize and improve with time. That’s the way this stuff goes.
I honestly feel the gains from all this, when all said and done, far outweigh the compromise on some changed links. And remember, ‘fuck Google!’
Offline
Re: User docs changes
Great stuff but …
… is it really, truly, absolutely, unequivocally necessary to shift all the tag index links from:
/docs.textpattern.com/tags/tag_nameto
/docs.textpattern.com/tags/reference/tag_nameIt does, I think, have a considerable knock-on effect, and it’s not just “some changed links”.
Aside from the fact that I’ve just gone through a hundred-odd textpattern.tips articles updating all the links from the old textbook wiki and .io domain links, not to mention the old txptips.com links (we have moved stuff around a fair bit over the years) the links were – I feel – already perfectly formed as they were without the word reference in there.
And textpattern.tips is not the only casualty: it’ll affect innumerable posts on the forum too. That will be the case with the panel pages too, which often also feature in plugin help docs. And if a redirect won’t work without putting in proxy-pages to forward on (negating the sub-folder file ordering gain), aren’t we breaking things more than necessary?
TXP Builders – finely-crafted code, design and txp
Offline
Re: User docs changes
What Jakob says is a very good point and something I hadn’t considered. Especially since we have no way to set up redirects on GitHub Pages (simplified Jekyll).
Probably substantial adverse SEO hit too.
Offline
Re: User docs changes
philwareham wrote #320455:
Especially since we have no way to set up redirects on GitHub Pages (simplified Jekyll).
Could it be done the old-fashioned way?
<!DOCTYPE html>
<meta charset="utf-8">
<title>Redirecting to /docs.textpattern.com/tags/reference/tag_name</title>
<meta http-equiv="refresh" content="0; URL=/docs.textpattern.com/tags/reference/tag_name">
<link rel="canonical" href="/docs.textpattern.com/tags/reference/tag_name">Offline
Re: User docs changes
michaelkpate wrote #320457:
Could it be done the old-fashioned way?
It can, but since Jekyll is a flat-file CMS there will be a lot of superfluous extra files needed to do this task.
Offline
Re: User docs changes
Hmm. We could leave the 165+ tag pages in that root and relocate the other 20 or so non-tag pages out instead. That would at least be fewer links to correct. The problem as it stands now is everything is mixed together in the /tags directory, and that’s not ideal.
Offline
Re: User docs changes
jakob wrote #320454:
Aside from the fact that I’ve just gone through a hundred-odd textpattern.tips articles updating all the links from the old textbook wiki and .io domain links, not to mention the old txptips.com links…
I have probably changed as many, if not more. So I know the feeling.
and it’s not just “some changed links”.
168, to be exact. Speaking of tag pages alone.
As for forum legacy, I don’t put much weight in that, personally. Links breaks all the time in here. For something like docs, that’s what the big ‘documentation’ link in the masthead is for. The default.
philwareham wrote #320455:
Probably substantial adverse SEO hit too.
I knew somebody would go there. But I beat you to it in my last line. ;)
Anyhoo, we’ll go with plan b, eh?
Offline
Re: User docs changes
Destry wrote #320464:
Hmm. We could leave the 165+ tag pages in that root and relocate the other 20 or so non-tag pages out instead.
If it’s less link upheaval and doesn’t taint the logic too much, then let’s move the few tags we’ve migrated already back into the old /tags directory, remove the remaining cloned tag docs from /tags/reference and just focus on gradually parsing them to replace the links to the 20-odd ones that have moved, as well as removing links to the panel docs.
Does it make more sense to do the tags after those supporting docs are in place to save having to do two sweeps? There are lots of links to [escape] and [cross-reference] etc
Last edited by Bloke (2019-12-11 15:48:23)
The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.
Txp Builders – finely-crafted code, design and Txp
Offline
Re: User docs changes
Bloke wrote #320468:
[cross-reference]
That one doesn’t change.
As for others, I would continue with removing panel page links (again, those docs are useless) and point to the page and form template sections indicated in issue 153, if such links are really needed in tag pages. I will cue drafting the ‘site structure’ doc that addresses all of that.
Back to the mines…
Offline
Re: User docs changes
Destry wrote #320469:
That one doesn’t change.
Oh, it will change now, I guess. Plan B. I get it.
Yeah. So much for progress, I guess. Let’s make two sites!
Offline
Re: User docs changes
Sorry for chiming in there so brutally. But thank you!
PS: If you’re working on files in a folder and have a good(-ish) text editor, you should be able to mass search and replace the /reference out the links. If you happen to use atom, then drop the folder on the atom app and then right-click and choose “search in folder”.
TXP Builders – finely-crafted code, design and txp
Offline
Re: User docs changes
jakob wrote #320471:
If you’re working on files in a folder and have a good(-ish) text editor, you should be able to mass search and replace the /reference out the links. If you happen to use atom, then drop the folder on the atom app and then right-click and choose “search in folder”.
Yeah, we should push forth with ‘Plan A’ since it’s so easy to fix those links. ;)
Truth is, it’s not about fixing links, really. In fact, as you point out, that part is kind of trivial if you use the right approach. The problem is that the /tags directory structure was not well considered in the beginning, and we were trying to improve it with includes and whatnot to help manage indexes consistently. So this was an attempt to improve the overall architecture of the docs site, not just tags alone. And fixing architecture out ranks the initial broken links, IMO, which can always be fixed with find/replace.
I think if the flat-file docs had been created as follows, where tags were logically organized by their category, which is how they are actually presented in docs anyway, nobody would be thinking twice about it now.
- tags
- article
- article
- article_custom
- article_id
- . . .
- index.md
- comment
- comment_anchor.md
- comment_email.md
- . . .
- index.md
- . . .
- shortcodes
- index.md
- tags-attributes-cross-reference.md
- . . .
- article
Giving URLs like:
https://docs.textpattern.com/tags/article/article_custom.md
https://docs.textpattern.com/tags/comment/comment_anchor.md
But this recent change was kind of a shortcut fix to at least get the tag pages isolated, and to use the parent /tags index as a complete directory index, as opposed to a somewhat confusing tags pages only index as it is now.
Just to explain the backstory/problem as I see it.
But we aim to please.
Offline
Pages: 1