[wp-docs] WordPress Guide in Codex

Mon Apr 2 08:46:25 UTC 2012

On 30/03/12 18:16, Lorelle on WordPress wrote:
> I've finally had time to go through the site's information. I found 
> errors and I know it's still in development. I don't see anything that 
> isn't already covered in the WordPress Codex and Learn WordPress, and 
> the inline help files. Did you have a specific article in mind that 
> you thought might port over to the Codex?

 From the first posts in this thread, what I understand is the gap in 
the code is one place where you can send new WordPress users to use 
their new WordPress site. Essentially, something as user friendly as 
Learn WordPress (https://learn.wordpress.com/) but targeted at people 
using self-hosted blogs.

So all the information is already on the codex but as I see it the 
challenge is to;

* cut this information down to say something about the same length as 
Learn WordPress
* add screenshots to make it more user friendly
* create a linear format that new user can work through
* self contained, so that it can be used as a base for other guides

The closest page I could come to that was this one.
http://codex.wordpress.org/WordPress_Quick_Start_Guide

It's linear and not too long. Generally with this kind of guide I think 
the tricky part is deciding what to leave out.

Although it's sometimes out of date, I think that the above quick start 
page is super useful and a good base to work from. It also comes up 
second on a search for 'wordpress guide' so it might be a good priority 
to update.  In a spirit of helpfulness, I'll compare it to the Learn 
WordPress and some specific articles that we created on floss manuals. 
Both resources have text and maybe even more usefully screenshots which 
can be ported across. I'll post links and then make some comments.

----//// begin comments

A couple of general observations I think generally it is probably a bad 
idea to link to external videos (especially pay for view ones) and 
external guides as they go out of date pretty quickly. Also, for me, 
references to altering css and template files don't have a place in a 
beginners guide apart from maybe in a section on taking your knowledge 
further.

** Installing, configuring and logging in

https://learn.wordpress.com/get-started/
http://codex.wordpress.org/WordPress_Quick_Start_Guide#Get_Set_Up
http://en.flossmanuals.net/wordpress/installling-on-a-server
http://en.flossmanuals.net/wordpress/logging-in

So the first observation is that Learn WordPress is much easier. There's 
not much we can do about that. Both the codex and flossmanuals ones seem 
out of date and could do with a rewrite and links updated. It does seem 
to make sense to link to the 5 minute install and detailed instructions 
at the Installing WordPress codex article here rather than to go into 
too much detail.

The quick start guide has some material in this section that I would 
probably move to a later section, this includes info on importing and 
site settings like permalinks, and comment settings. The LWP (Learn 
WordPress) quickly moves on to an overview the dashboard. I think is a 
good idea.

It would be good to have a quick guide with screen shots on how to log 
in to your blog.

**Intro to Dashboard / General Settings

http://codex.wordpress.org/WordPress_Quick_Start_Guide#Explore_Your_New_WordPress_Blog
https://learn.wordpress.com/get-acquainted/
http://en.flossmanuals.net/wordpress/introduction-to-the-dashboard/

LWP and the FM (floss manuals) have short intro to the dashboard and 
general settings with some screen shots. We could just port some of this 
across and remove the out of date content.

The entry on admin panel in codex is too detailed and non-linear 
http://codex.wordpress.org/Administration_Panels
The codex entry on the dashboard didn't seem focused on the priorities 
of the new user - http://codex.wordpress.org/Dashboard_Screen

** Get Focused

https://learn.wordpress.com/get-focused/

The FM guide and quick guide don't contain anything on content but that 
might be a nice thing to do as it breaks up the techiness of the guide.

** Create Content

http://codex.wordpress.org/WordPress_Quick_Start_Guide#Create_Content
https://learn.wordpress.com/get-published/
https://learn.wordpress.com/get-flashy/
http://en.flossmanuals.net/wordpress/add-a-post

For all of these guides there are sub entries for the different types of 
entries, posts, pages, adding images, using wysiwig, adding links, tags, 
categories etc,

The LWP guide is really pretty short and links out to additional content 
for more complicated steps like creating custom menus and adding image 
galleries.

The FM guide breaks up different functions like adding images, videos, 
image galleries into separate sections and gives step by step 
instructions with screenshots.

The quick guide has some of these sections but could do with some 
screenshots.

I think that ideally these section would be a self contained, visual 
summary which gives a step by step example of how to do the most simple 
application of a feature but which doesn't aim at completeness, linking 
out to more comprehensive information. I've tried to do that here. Some 
may find the simplification offensive (sorry!).
http://en.flossmanuals.net/wordpress/using-categories-and-tags/

There are loads of screenshots which can be ported from FM to codex for 
these sections.

Also missing in the codex is a quick into to adding user and roles - 
there is one in FM
http://en.flossmanuals.net/wordpress/user-roles
which is a summary of this codex page - 
http://codex.wordpress.org/Roles_and_Capabilities
with a step by step guide with screenshots on how to add users.

** Style your site

http://codex.wordpress.org/WordPress_Quick_Start_Guide#Style_Your_Site
https://learn.wordpress.com/get-customized/
http://en.flossmanuals.net/wordpress/themes  and see other chapters in 
the Design section

All three guides have got some good sections on themes and widgets. 
There is some very user friendly text in LWP which could add something

I also really like the idea of including something about using wordpress 
to create a website.
LWP links to this. 
http://en.support.wordpress.com/using-wordpress-to-create-a-website/
FM has this quick guide - 
http://en.flossmanuals.net/wordpress/making-a-website-instead-of-a-blog/
and this page on menus which I think is very valuable in this situation.
http://en.flossmanuals.net/wordpress/using-menus/

I think that the above menu page would be a good replacement for this 
section
http://codex.wordpress.org/WordPress_Quick_Start_Guide#Configure_How_Your_Pages_Appear

** Add More Functionality / Plugins

http://codex.wordpress.org/WordPress_Quick_Start_Guide#Add_More_Functionality
http://en.flossmanuals.net/wordpress/intro-to-plugins/

It is a big area to cover and both guides take the same tactic of 
describing what plugins are, covering how to install them, giving 
examples of a few plugins and how they work.

This is a useful page to link to
http://codex.wordpress.org/Managing_Plugins
It describes installing plugins with the built installer (with manual 
installation as a fall back) which seems like a more user friendly 
process than via ftp which is recommended in the current guide.

** Building readers

https://learn.wordpress.com/get-connected/

It might be nice to mirror this section in LWP but rewritten with some 
suggested tools like cross posting to twitter or a 'follow me' plugin.

** Understand the Code More / Advanced Admin

http://codex.wordpress.org/WordPress_Quick_Start_Guide#Understand_the_Code_More
http://en.flossmanuals.net/wordpress/security/

Both FM and the quick guide have sections about taking it beyond the 
basics, analytics, upgrading, securing your installation. I guess the 
key here is to keep it brief and link to good beginner friendly pages on 
the codex.

I think the approach on the quick guide is good in terms of scope, 
modifying themes and understanding the loop. However, I think they need 
to lead the user by the hand a lot more and give some practical examples 
before sending new users off deep into the heart of the codex. I know 
Martin who has been working on the FM guide is up for doing some work in 
this area soon so I can keep you updated on this.

----//// end comments

I hope that these observations and suggestions are taken in the spirit 
of collaboration in which they are intended.  I am very happy that there 
is going to be an updated guide.

I only have sporadic access to good Internet and so I tend to sprint on 
these kinds of projects which is not ideal sometimes, as all the 
suggestions come at once. I am happy to take on some work transferring 
some / any of content to the codex if I am given some guidance on where 
to put it.

nice one
Mick