Kenshino commented 3 years ago

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:

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

What's next?

Pick up an article via creating an issue
If you create an issue we assume you're working on it
When you're ready, via the Projects link, push it into the Content Review Column
One of us will review it for "official stamping", any others can provide suggestions, it's open source
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
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 commented 3 years ago

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 commented 3 years ago

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

zzap commented 3 years ago

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

femkreations commented 3 years ago

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

INSTALLATION

BASIC USAGE

BASIC ADMINISTRATION

CUSTOMIZING

MAINTENANCE

SECURITY

TROUBLESHOOTING

ADVANCED

agnieszkaszuba commented 3 years ago

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 commented 3 years ago

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 commented 3 years ago

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