textpattern.github.io
textpattern.github.io copied to clipboard
textpattern
page: Troubleshooting common problems
Current page... https://docs.textpattern.com/installation/troubleshooting-textpattern
Duplicate file as... https://docs.textpattern.com/setup/troubleshooting-common-problems (Don't use 'Textpattern' in titles or file names.)
Maintain new file path in... https://docs.textpattern.com/index2
Proposed page topic
A single page that systematically addresses the most common and/or serious troubleshooting issues. Each problem is a Contents (toc) item and no further page structure should be used that messes up the contents list.
Additional resources to audit
- [ ] /_recycle/needless-faqs (All the offline faqs. If none are deemed useful, those files will finally be removed from the tree.)
- [ ] /faqs (whatever is left; it gets cleaned out, too)
- [ ] forum thread...
- [ ] forum thread...
- [ ] etc
I've copied this over to /setup and started editing it. Folded one FAQ in so far. Will merge the rest of the useful ones as time permits.
Should we just delete the individual FAQ docs or are they linked from elsewhere and need redirecting?
Only what's in /faqs is live, maybe four, I think; directly from the homepage, is all I'm aware of. But everything in _recycle is already offline, at least in user docs. I don't know about elsewhere. I hope not.
So I say just delete them. I think redirecting is a problem in the user docs anyway. There's a convo between Phil and Pete on this. Pete has the redirecting role, if it can be done, just flag him on the issue. But for these, I wouldn't even bother.
Pete has the redirecting role, if it can be done
Short answer: not easily. GitHub Pages has limited ways to do this in a sane way, short of running our own docs site using this as a the source, I'm not clear how we can achieve this. Given the (perceived) traffic the site gets, I suspect a) the search engine visitors will be few; and b) we can tart up the 404 page with additional links should someone land on a moved page.
This doc maybe needs a section for how to troubleshoot upgrading a very old installation to current version and system requirements. Or maybe this should be its own document? This is a common area around which many questions are raised in the forum. That could be the basis for researching the right scenarios/responses to structure the doc by.
See moving an installation doc...
It currently has the following two related sections:
- System requirements, which currently links to the troubleshooting doc
- Change password, which describes a different method than what is in the troubleshooting doc.
How can we better harmonize these two pages?
Regarding troubleshooting old installations, @petecooper wrote a nice article somewhere about how to do it in two jumps when updating from old versions to 4.2.0, then from there to the latest. I'm sure it's lurking somewhere so if we can find it, ether link to it or take it from its current location and put it here.
As you say, we should also perhaps curate some of the forum responses or avenues for exploration we give for common issues with upgrades, such as DB collation going wonky and things like weird errors due to the files not being completely uploaded or still partially cached.
we should also perhaps curate some of the forum responses or
As I find anything in forum, I'll add it to the research/audit list started in head post. Feel free to edit.
Change password, which describes a different method than what is in the troubleshooting doc.
Do you think one password reset instruction is better/safer/easier over the other? My inclination is to pick the simplest/robust one and support that instruction only. For example, if the pass reset instruction in the current Troubleshooting doc is better, then I will drop the section in the 'moving an install' doc and simply link to the Troubleshooting doc instead. Easier.
Again, that dispersed redundancy is a killer to maintain for the skeleton crew. In such cases, 'maintain' is generally what doesn't happen over time. ;)
Note that the reset method for MySQL 5.* is different to 8.* -- I have a snippet somewhere that @bloatware built that works for both, I'll search for it.
Regarding troubleshooting old installations, @petecooper wrote a nice article somewhere about how to do it in two jumps when updating from old versions to 4.2.0, then from there to the latest.
https://forum.textpattern.com/viewtopic.php?pid=311659#p311659