ρ (rho) wrote in lj_userdoc,
ρ
rho
lj_userdoc

Simplifications

One of the things that the userdoc elements of style mention is that FAQs should have an average reading level of about 8 to 9. And, well, they don't. alsatia ran all the FAQ categories through MSWord's grammar checker and the lowest reading level of any fo them is comments at 10.5. Several of the categories are at 12.0 which is the highest that Word will return. This is a problem.

There are two main reasons for this. The first is all the URLs that we have in the middle of the FAQs. These quite seriously hinder readability. The second is unnecessarily complex language. We have a lot of convoluted sentence structures, superfluous phrases, and big words.

So, what I'm proposing to do has two parts to it. Firstly, I'm proposing to remove all of the tangential links from the main body of the FAQs, and put them in a "further reading" section at the bottom. I think that keeping these links in somewhere is important because we don't want people to read "you can only do $foo if you have a paid account" and think "huh? what's a paid account?" and not have the link at hand. On the other hand, most people reading through the FAQ will already know what paid accounts are, and the extra explanation and URLs just makes it harder to read.

Secondly, I propose to try to simplify the wording of the FAQs by getting rid of all the twiddly sentence strustures and the likes. This will make the prose less eloquent, but I think that less eloquent prose is a small price to pay for increasing readability.

As an example, here's what I did to FAQ 27, Why am I receiving a "Cannot contact server" error when I try to use my client? (which I picked out entirely at random)

There are several reasons why your client may lock up when you try to log in. The most common cause for this is a proxy. This means you don't have a direct connection to the Internet and the client does not know how to contact the server.They are commonly used by businesses or on other networks. If you were able to successfully connect from your current computer in the past, it is possible that your Internet Service Provider (ISP) has changed its proxy settings recently. You will need to contact your ISP for more information.

If you know that you are not accessing the internet through a proxy, you may be experiencing problems with a firewall. If you use a firewall, make sure that you have listed the client under the programs that are allowed to access the Internet. You may have to read your firewall's documentation to learn how to do this. Even if you haven't installed a firewall yourself, some operating systems come with a pre-installed firewall.

If this doesn't help, you should check if to see if LiveJournal.com is actually down. Try going to http://www.livejournal.com/ in your web browser, or see http://status.livejournal.org/. At peak load times you may receive the "Cannot contact server" error because of the high number of users attempting to contact the servers.

The Visions and Semagic Clients for Windows most commonly experience this problem. Information about editing your proxy settings to allow either of these clients access to the Internet is available at http://www.livejournal.com/users/howto/23617.html.

If you've tried all of the solutions above and you're still having problems then file a Support Request under the Clients category. You can do so at http://www.livejournal.com/support/.

FURTHER READING
Why am I having problems accessing pages on LiveJournal?
http://www.livejournal.com/support/faqbrowse.bml?faqid=116

The howto journal:
http://www.livejournal.com/userinfo.bml?user=howto

This reduces the reading age for this particular FAQ from 12.0 to 10.3. Not great, but a whole lot better than it is right now.

What I'm proposing to do is have a discussionabout this, and then in a couple of days, provided the consensus is positive, to go throught the entire FAQ, and make similar changes for each question. I imagine thatI'd probably do about a category a day, post them up for discussion here, and then make the changes a couple of days later.

So. Thoughts?

Edit to add: This is now being discussed in lj_docadmin to decide the best way of doing it that will allow us to keep our sanity. If it takes a while and it looks like we've forgotten about it, we almost certainly haven't.
Subscribe
  • Post a new comment

    Error

    Comments allowed for members only

    Anonymous comments are disabled in this journal

    default userpic

    Your reply will be screened

    Your IP address will be recorded 

  • 11 comments