Some end-user docs are too technical

[Kenshino]

---

Issue Description

Some end-user docs are too technical and are reflective of a by-gone era where some hosts simply failed at supporting WordPress. Hence needing us to provide documentation.

e.g. https://wordpress.org/support/article/using-permalinks/ starts talking about htaccess etc. Really, we ought to just be telling the end-user to contact their host and work it out - perhaps with a recommended text.

URL of the Page with the Issue

https://wordpress.org/support/article/using-permalinks/

Section of Page with the issue

Why is this a problem?

I believe the technical bits (not just in this link) confuses end users.

Suggested Fix

Reassess all pages with technical bits and move those to DevHub if necessary.

How to work on these articles

What is too technical? Roughly explained:

1. no code except for wp-config.php file
2. only what can be done in wordpress dashboard
3. no hosting provider specific docs, no server configuration etc

What's next?

1. Pick up an article via creating an issue
2. If you create an issue we assume you're working on it
3. When you're ready, via the Projects link, push it into the Content Review Column
4. One of us will review it for "official stamping", any others can provide suggestions, it's open source
5. Once the content is verified to be good, it needs to be pushed into the Implementation column so teh content can be transcribed to WordPress.org
6. After implemented, the issue needs to be pushed into the Style Guide review column so that someone can apply/review if the article is following the style guide

---

Project board: https://github.com/WordPress/Documentation-Issue-Tracker/projects/2

[zzap]

I suggest we use this issue to gather all similar articles and then, by the topics covered, see where it should live. We are missing a space for some common topics, shared among all developers, such as Localisation and Internationalisation, Escaping, Sanitising.. .htaccess etc

[Kenshino]

Let's create a separate issue for dev docs @zzap - Can you pick that up?

[zzap]

Done https://github.com/WordPress/Documentation-Issue-Tracker/issues/42

[femkreations]

Here is the list of articles in the end-user docs that have technical content. The list is organized based on the categories. There may be overlaps as some of the articles are in multiple categories.

GETTING STARTED

• [x] https://wordpress.org/support/article/restoring-your-database-from-backup/#using-mysql-mariadb-commands  

• [x] https://wordpress.org/support/article/upgrading-wordpress-extended-instructions/#step-6-download-and-extract-the-wordpress-package

• [x] https://wordpress.org/support/article/upgrading-wordpress-extended-instructions/#step-7-delete-the-old-wordpress-files  

• [x] https://wordpress.org/support/article/backing-up-your-wordpress-files/  

• [x] https://wordpress.org/support/article/resetting-your-password/#through-mysql-command-line

• [x] https://wordpress.org/support/article/resetting-your-password/#through-phpmyadmin

• [x] https://wordpress.org/support/article/resetting-your-password/#through-ftp

• [x] https://wordpress.org/support/article/resetting-your-password/#through-wp-cli

• [x] https://wordpress.org/support/article/resetting-your-password/#using-the-emergency-password-reset-script  

• [ ] https://wordpress.org/support/article/creating-a-search-page/  

• [x] https://wordpress.org/support/article/managing-plugins/#wordpress-plugin-tips

• [x] https://wordpress.org/support/article/managing-plugins/#advanced-troubleshooting  

• [ ] https://wordpress.org/support/article/using-smilies/#how-can-i-have-different-smiley-images-appear

• [ ] https://wordpress.org/support/article/using-smilies/#smiley-css

• [ ] https://wordpress.org/support/article/using-smilies/#why-are-my-smiley-images-blank  

• [ ] https://wordpress.org/support/article/using-themes/#adding-new-themes-manually-ftp  

• [ ] https://wordpress.org/support/article/phpmyadmin/  

• [ ] https://wordpress.org/support/article/giving-wordpress-its-own-directory/  

• [ ] https://wordpress.org/support/article/using-cpanel/  

• [x] https://wordpress.org/support/article/backing-up-your-database/

• [ ] https://wordpress.org/support/article/using-filezilla/  

• [ ] https://wordpress.org/support/article/ftp-clients/  

• [ ] https://wordpress.org/support/article/roles-and-capabilities/  

• [x] https://wordpress.org/support/article/updating-wordpress/  

• [ ] https://wordpress.org/support/article/glossary/

INSTALLATION

• [ ] https://wordpress.org/support/article/before-you-install/  
• [ ] https://wordpress.org/support/article/installing-wordpress-on-your-own-computer/  
• [ ] https://wordpress.org/support/article/how-to-install-wordpress/  
• [ ] https://wordpress.org/support/article/installing-multiple-blogs/  
• [x] https://wordpress.org/support/article/login-trouble/  
• [ ] https://wordpress.org/support/article/faq-installation/  
• [ ] https://wordpress.org/support/article/test-driving-wordpress/  
• [ ] https://wordpress.org/support/article/moving-wordpress/  
• [ ] https://wordpress.org/support/article/create-a-network/  
• [ ] https://wordpress.org/support/article/using-cpanel/  
• [ ] https://wordpress.org/support/article/before-you-create-a-network/  
• [ ] https://wordpress.org/support/article/automated-installation/  
• [ ] https://wordpress.org/support/article/configuring-automatic-background-updates/  
• [ ] https://wordpress.org/support/article/creating-database-for-wordpress/  
• [ ] https://wordpress.org/support/article/nginx/

BASIC USAGE

• [x] https://wordpress.org/support/article/using-permalinks/  
• [ ] https://wordpress.org/support/article/finding-wordpress-help/

BASIC ADMINISTRATION

• [ ] https://wordpress.org/support/article/https-for-wordpress/#best-practices-for-https-for-wordpress  
• [ ] https://wordpress.org/support/article/faq-working-with-wordpress/

CUSTOMIZING

• [x] https://wordpress.org/support/article/restoring-your-database-from-backup/  
• [ ] https://wordpress.org/support/article/moving-wordpress/  
• [x] https://wordpress.org/support/article/managing-plugins/#wordpress-plugin-tips

MAINTENANCE

• [x] https://wordpress.org/support/article/wordpress-backups/  
• [x] https://wordpress.org/support/article/restoring-your-database-from-backup/  
• [ ] https://wordpress.org/support/article/moving-wordpress/  
• [ ] https://wordpress.org/support/article/optimization/  
• [ ] https://wordpress.org/support/article/search-engine-optimization/#robots-txt-optimization  
• [ ] https://wordpress.org/support/article/optimization-caching/  
• [ ] https://wordpress.org/support/article/plugins-themes-auto-updates/

SECURITY

• [ ] https://wordpress.org/support/article/hardening-wordpress/  
• [ ] https://wordpress.org/support/article/brute-force-attacks/  
• [ ] https://wordpress.org/support/article/faq-my-site-was-hacked/  
• [ ] https://wordpress.org/support/article/administration-over-ssl/  
• [ ] https://wordpress.org/support/article/https-for-wordpress/

TROUBLESHOOTING

• [ ] https://wordpress.org/support/article/htaccess/  
• [ ] https://wordpress.org/support/article/common-wordpress-errors/  
• [x] https://wordpress.org/support/article/login-trouble/  
• [ ] https://wordpress.org/support/article/debugging-in-wordpress/  
• [ ] https://wordpress.org/support/article/faq-troubleshooting/  
• [x] https://wordpress.org/support/article/resetting-your-password/  
• [ ] https://wordpress.org/support/article/loopbacks/  
• [ ] https://wordpress.org/support/article/moving-wordpress/  
• [x] https://wordpress.org/support/article/restoring-your-database-from-backup/  
• [x] https://wordpress.org/support/article/managing-plugins/

ADVANCED

• [ ] https://wordpress.org/support/article/brute-force-attacks/  
• [ ] https://wordpress.org/support/article/htaccess/  
• [ ] https://wordpress.org/support/article/administration-over-ssl/  
• [ ] https://wordpress.org/support/article/installing-wordpress-in-your-language/  
• [ ] https://wordpress.org/support/article/multisite-network-administration/  
• [ ] https://wordpress.org/support/article/custom-fields/  
• [ ] https://wordpress.org/support/article/post-status/#custom-status  
• [ ] https://wordpress.org/support/article/post-types/  
• [x] https://wordpress.org/support/article/backing-up-your-database/  
• [ ] https://wordpress.org/support/article/using-cpanel/  
• [ ] https://wordpress.org/support/article/debugging-in-wordpress/  
• [ ] https://wordpress.org/support/article/phpmyadmin/  
• [ ] https://wordpress.org/support/article/writing-code-in-your-posts/  
• [ ] https://wordpress.org/support/article/using-your-browser-to-diagnose-javascript-errors/  
• [ ] https://wordpress.org/support/article/test-driving-wordpress/  
• [ ] https://wordpress.org/support/article/multilingual-wordpress/  
• [ ] https://wordpress.org/support/article/optimization-caching/  
• [ ] https://wordpress.org/support/article/create-a-network/  
• [ ] https://wordpress.org/support/article/installing-multiple-blogs/  
• [ ] https://wordpress.org/support/article/changing-the-site-url/  
• [ ] https://wordpress.org/support/article/before-you-create-a-network/  
• [x] https://wordpress.org/support/article/managing-plugins/  
• [ ] https://wordpress.org/support/article/moving-wordpress/  
• [ ] https://wordpress.org/support/article/hardening-wordpress/  
• [ ] https://wordpress.org/support/article/optimization/  
• [ ] https://wordpress.org/support/article/nginx/  
• [ ] https://wordpress.org/support/article/brute-force-attacks/  
• [ ] https://wordpress.org/support/article/htaccess/  
• [ ] https://wordpress.org/support/article/multisite-network-administration/  
• [ ] https://wordpress.org/support/article/administration-over-ssl/

[agnieszkaszuba]

Here are some additional articles from the Getting Started category that may have too technical content:

• [ ] https://wordpress.org/support/article/overview-of-wordpress/ - I'd suggest removing the 'based on PHP and MySQL.' part since non-developers wouldn't know what that is, or alternatively linking to definitions of PHP and MySQL.
• [ ] https://wordpress.org/support/article/glossary/#absolute-path - the last paragraph may be too technical
• [ ] https://wordpress.org/support/article/glossary/#binaries - end-users may not know what 'compiling' means in this context
• [ ] https://wordpress.org/support/article/glossary/#bookmarklet
• [ ] https://wordpress.org/support/article/glossary/#filter
• [ ] https://wordpress.org/support/article/glossary/#hook
• [ ] https://wordpress.org/support/article/glossary/#htaccess
• [ ] https://wordpress.org/support/article/glossary/#plugin
• [ ] https://wordpress.org/support/article/glossary/#relative-uri - would be good to provide a definition of URI somewhere, and the difference between URI and URL
• [ ] https://wordpress.org/support/article/glossary/#ssh - would be good to provide a definition for TCP/IP

[hannaw93]

More articles from the Getting Started category that may have too technical content:

• [ ] https://wordpress.org/support/article/login-trouble/ it would be helpful to add the link about the wp-config.php file (and where to find it) to the instructions where it is mentioned.
• [ ] https://wordpress.org/support/article/debugging-in-wordpress/ starting from the paragraph on WP_DEBUG_LOG #, is a a bit too technical (including possibly non-familiar terminology)
• [ ] https://wordpress.org/support/article/faq-troubleshooting/ last section has long sentences that are bit too loaded with different terms, including abbreviations
• [ ] https://wordpress.org/support/article/administration-over-ssl/ would be good to link an article about SSL in general

[zzap]

The workflow for this one

• you select a number of links from that issue,
• open your own issue a paste all those links in there
• go back to parent issue and link your own issue in the comment
• I'll go through previous comments and strike through + link back links you selected
• copy the part of article that needs editing into google doc and make the edits and submit for review
• once the too technical part is edited, then review the whole article for style guide

[femkreations]

Refer #70 for the URLs I am working on.

[femkreations]

Working on #72 Managing Plugins URL

[femkreations]

Working on #73 Updating and Upgrading WordPress instructions

[femkreations]

Working on #79 Resetting Password

[femkreations]

Working on #82 WordPress Backups, Backing Up Your Database, Restoring Your Database From Backup, Backing Up Your WordPress Files