[wp-docs] List of options WP 1.2 Alpha 2 04-18 CVS

[Matthew Thomas]

On 19 Apr 2004, at 11:33 AM, Carthik A Sharma wrote:
> ...
> The document describing the Options administration page for 1.2.alpha2 
> is attached to this mail. Feedback, comments, bouquets, biscuits 
> welcome.

Hi, I designed the Options interface for 1.2 (and The Other Matt did a 
beautiful job of implementing it). If I did my job properly, :-) people 
should hardly need to go to the help.

When they *do* go to the help, it'll usually be because they have a 
really curly question that isn't covered by the interface text.

So, when writing help, *please don't repeat stuff* that's in the 
interface already. If you do that, people will get frustrated and 
annoyed (especially if you don't say anything else).

For example:
>
> There are Eight groups of Options. These are:

People can see that already, by looking at the tabs. This is a table of 
contents -- there's no need to disguise it as actual help text when 
it's not.

> General Options : This set of options relate to the settings that 
> define the Weblog as a whole
> 	* Weblog title: The title of your Weblog.
> 	* Tagline: In a few words, explain what this weblog is about.
> 	* Web address (URI): The desired web address of the weblog (eg. 
> http://www.example.com/wordpress)
> 	* E-mail address: 	The email address of the administrator. This 
> address is used only for admin purposes.

All of this text is redundant, because it's in the interface already. 
In the help you should be answering the curly questions, the questions 
that would cause too much clutter if we'd answered them in the 
interface itself. Things like:
*   I changed the title here and it didn't change in my
     Weblog. Why? (Probably because you hard-coded the title
     into your template.)
*   Where does the tagline get used?
*   Should I put "/" at the end of the Web address? Does
     it matter?
*   What are those "admin purposes"? What gets e-mailed?
*   Will WordPress send my e-mail address to anyone else?

*Don't put the actual questions* in the help text. Just write a few 
paragraphs that answer all of the questions at once, as concisely as 
possible.

> 	* Membership: 	You can control whether visitors to the blog can 
> register themselves, and whether registered users can post entries to 
> the blog.

Again, redundant. Sorry to be such a downer ... Writing good help text 
is *hard*. If it was easy, it wouldn't be necessary.

You have to think of what questions people might be asking. For these 
fields it might be:
*   Why would I want people to register? What's the point?
*   How do I find out who's registered?

> 	- Date and Time Options :
> 		* Times in the weblog should differ by: 	The hours by which your 
> time differs from the displayed GMT time. This will ensure that your 
> articles and weblog maintain correct times. This is useful when you 
> and your server are in different time zones.

I suggest replacing this explanation with two examples, one negative 
and one positive.

>   		* Default date format: 	The format for displaying the date on your 
> weblog.
> 		* Default time format: 	The format for displaying the time on your 
> weblog.

Rephrasing = Redundant. Instead, maybe show a couple of examples of 
formats and how to achieve them. (And maybe in 2.0 we'll have cool date 
and time format interfaces with live previews, so we won't need this 
help at all ...)

> Writing Options : This set of options control the way you write new 
> articles.
> 	* When starting an post, show: 	Choose the preferred writing 
> interface.

Huh? Instead, explain why I'd choose each one.

> 	* Size of the writing box: 	The number of lines in the text-box for 
> posts.

"Lines"? Lines of what? Instead, explain briefly why you'd want to make 
it smaller or larger.

> 	* Formatting:	Choose whether Wordpress should automatically convert 
> emoticons to images, and whether WordPress should automatically 
> correct invalidly nested XHTML in posts.

Rephrasing = Redundant. Instead, answer the likely curly questions:
*   What emoticons can I use, exactly?
*   I have this turned on but my emoticons aren't working.
     Why? (Coz the smileys folder is missing, etc.)
*   Why would I ever want to turn the XHTML correction off?

> 	- Update Services
> 		* Enter the sites that you would like to notify when you publish a 
> new post.

*   What? Why would I want to do that?

> 	- Writing by Email
> 		* Mail server:	The mailserver where the posts will be sent
> 		* Port:	The port used to access the mails on the mailserver
> 		* Login name: 	The login name for the mail account to which posts 
> will be sent
> 		* Password: 	The password for the above login name

*   Mail server? Huh? What's that?
*   How do I find out what to put in these fields?

> 		* Usual category: 	The category in which posts by email should be 
> published in

*   Why would I want to set a special category for e-mailed
     posts?

> Reading Options : This set of options control the way your posts are 
> displayed.
> 	- Front Page
> 		* Show the most recent: 	The number of posts to be displayed on the 
> Weblog's main page. The options for display include the chosen number 
> of posts, days, or paged posts.

Yes, but we know all that already, because it's in the interface. 
Instead:
*   Why would I want to choose more or fewer? (Convenience,
     bandwidth, etc)

> 	- Syndication Feeds
> 		* Show the most recent: 	The number of posts that should appear in 
> your weblog's syndication feeds
> 		* For each article, show: 	Choose to show the full text, or the 
> summary of the article

Same here.

> 	*  Encoding for pages and feeds: The character encoding format to be 
> used for your articles and feeds

*   UTF-8 is recommended. Why would I want to use anything
     else? And what would it be?

> 	*  Choose whether WordPress should compress articles (gzip) if 
> browsers ask for them

*   What's the point of doing that?
*   Oh, cool. So why would I ever want this turned off?

> Discussion Options : This set of options control discussions on your 
> weblog.
> ...

I see you haven't got to this section yet. Remember: What are the curly 
questions? Explain the tradeoff between easier commenting and easier 
spamming.

> Miscellaneous Options : Just that!

When writing help text you have to be really careful not to seem 
condescending. I once revised the help file for an accounting program, 
and a sizable chunk of my job was removing all the occurrences of 
"Simply" at the start of a sentence explaining how to do something, 
because they were condescending. "Just" is just as bad.

> 	- Choose whether or not to allow users to upload files.
> 		If file uploads are allowed, the following options
>  apply :
> ...

I have to go back to lectures ... See if you can think of the rest of 
the curly questions yourselves. If you're short of ideas, browse the 
support forums for inspiration. :-)

-- 
Matthew Thomas
http://mpt.net.nz/