[wp-docs] Leveraging the forum

[Chris Waigl]

On Mon, 13 Dec 2004 21:24:26 -0500, Carthik Sharma <carthik at gmail.com> wrote:
> Regarding leveraging the forums, I collect fodder for future
> documentation from the forums at a sub page of my user page[1]. Would
> it be useful if we had a page in the main namespace, where people
> could add forums nuggets that other could then attempt to make docs
> out of?

I just saw that (by pure chance) and am about to use my user page in a
similar way. A central page would be a very good idea IMHO.

> [...] Say, why don't we grow our Codex organically, starting from the front
> page. 

Yes!!!! Sorry for the multiple-bang thing, but Codex needs to be grown
from both sides.

Podz was wondering about a) persistent complaints about the
documentation and b) the sluggish response to the Wiki Day. Both might
come partly from the same reason: There's already a lot of good doc
available, but you just don't find it, and there's no way to browse it
in a logical format. (As an experiment, I tried searching for "change
colors" -- no results, not even inside pages, even though we have
quite a bit about CSS).

Not even the "Wiki Day" page is linked from the front page... and as
someone who hasn't done much on Codex, I don't dare to do that...

I've been helping a number of people on irc and sometimes on the
forums, and I have a bit of experience writing documentation, but with
the Wiki, I just don't know where to start because I don't know how
what I'm going to write fits in with an overall structure. This, I
believe, is an inherent difficulty in using wikis for documentation:
not that we shouldn't do it (it has the huge advantages that it makes
contributing technically easy and creates a uniform appearance), but
we need to cater for this.

At the moment, many many pages are orphaned. Ideally, all pages that
tell a user how to do something should be linked from somewhere. This
index doesn't need to be on one page (and shouldn't resemble the one
on the old wiki), and its front/welcome page should employ a simple
language. New users shouldn't be confronted with terms like
"customization", "template tags" and "css tips" on their first foray
into WP.

I looked into bloggers documentation (http://help.blogger.com/). It
is, IMHO, far from ideal and barely good, but it has the advantage of
cutting up the tasks in a transparent manner.

What I'd suggest (off the top of my head, in no definite order; all of
these may link to additional, more specific pages and of course be
linked to each other, even across categories; they also should link to
the glossary):

- WP Basics:
  * Welcome/Overview
  * What is a blog?
  * WP blogs and search engines
  * Can I have a collective blog?
  * Can WP power multiple blogs?
  * Can I have a blog in a language other than English?
  * What browsers are supported?
  * Can I use desktop blogging software?
  * What is new in version 1.3
  * Installing WP (links to pages that explain a particular step in
detail, and to common installation problems) +++
  * Upgrading from v. 1.2.1
  ...

-  Working with WP
  * Posting and editing an entry
  * The "Blog this" bookmarklet
  * Working with categories
  * Links and blogrolls
  * Working with multiple users and user levels
  * What are Pages and how to create one? +++
  * How does WP generate my site?
  * Changing date formats and time zones
  * Changing fonts and colors
  * Changing your blog language
  * Designing your own blog +++
  * What is a template? (general overview, css vs. php files, the
split-up template structure)
  * Making changes your template (-> links to the Template Tags page)
  * Editing your template files from inside WP
  * How to get the date displayed for every blog entry
  * Working with FTP +++
  * What is a theme and how to install one?
  * Posting images / media files
  * What are "clean/pretty" URLs and how do I get them
  * Fighting comment spam
  * Posting by email
  * How to back up your blog
...

- Troubleshooting
  * Common installation problems
  * I've lost my password
  * I can't log in
  * "headers already sent"
  * (problems that come from not enabling cookies) not necessarily on one page!
  * (problems that come from wrong php versions) not necessarily on one page!
  * (problems that come from using a windows server) not necessarily
on one page!
  * 
  * (other common problems go here)

- Advanced topics:
  * Creating your own themes +++
  * Integrating WP into an existing site
  * How to have a different appearance for different pages / categories ...
  * How to (do-whatever-requires-a-plugin) (several pages)
  * Available plugins (has to be clarified: how much info on the wiki?
link to a central site or not?)
  * How to (do-whatever-requires-more-php-than-a-template-tag) (several pages)
  * Using my-hacks.php
  * How to integrate WP with (iffy-spiffy-picture-gallery-forum)
  * CSS Tips and Tricks
  * Moving your blog to a new host / domain
  * Importing your old blog (-> blogger, MT, b2, whatever)
  * Exporting WP
  * How to use WP as (something-other-than-a-blog)
  * Deleting your blog
  * Writing your own plugins +++
...

Those points marked with "+++" might better go into a "WP Guides"
section (ie more complete, general tutorials). In this case, the
respective section would still need to have a more specific item that
covers a few common tasks and links to the complete guide.

The more advanced topics that require an outside plugin should
probably not be treated like the tasks that can be carried out using
WP's tools alone. Maybe an entry called "How to do something not
covered here" that basically says "there may be a plugin available for
what you want to do" and links to the plugins overview page would be a
good idea.

If you think that a structure vaguely resembling this is a good idea,
I'll wait for your input and use my wiki user page for a tentative,
cleaner and more complete version. I'd also like to attack a few of
the more basic points for the Wiki day.

-- 

Chris Waigl
blog: http://serendipity.lascribe.net/
experiments: http://chrysalidesque.f2o.org