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

[Carthik A Sharma]

Hi Matthew,

The document I wrote was in response to a user request for a page that 
"lists all the options, so I know where to look in order to change some 
setting." The request is at http://wordpress.org/support/9/4275#post-7

I see how you mean to say that there should be a document that addresses 
the curly questions. That could be another one, or perhaps I could 
change this one using your suggestions. That would be more like a 
Options UI faq.

I only meant this to be the page where you go an look up the page where 
a setting is listed.

I will try to create a settings/options faq, but as you noted, that will 
take some time :)

Thanks for the detailed comments.

Carthik.


Matthew Thomas wrote:

> 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. :-)
> 

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 187 bytes
Desc: OpenPGP digital signature
Url : http://socrates.scdns.net/pipermail/docs_wordpress.org/attachments/20040418/ded9b632/signature.bin