WebPlatform.org from a technical writing perspective

Guest post by Allen Brodsky*:
WebPlatform.org is a significant, cooperative effort by many people from competing companies to encourage innovation on the web: its goal is to provide total information about web development in one place. Here, I take a look at the Alpha version from a technical writing perspective.
The site is attractive and logically organized. However, the home page design seems to favor the repeat visitor at the expense of the first-timer. The first-time visitor wants to find out what kind of information and support is on the site, and where (on the site) to find it. Alas, (as some early visitors have commented) there’s no obvious or intuitive place to start reading or exploring:

Instead, the current home-page structure forces that visitor to pick a link and click, to dive in and explore the site to discover what it offers. This approach makes for an interesting but not quick or efficient experience.
The main page links, at the top of the home page, are not ordered intuitively. For example, “Docs” would seem to be the most important or more popular topic, but I would expect it to be followed by “Tutorials,” like docs, a way to learn. Likewise, the arrangement of the “Hot topics” links seems random. Here, alphabetical order would make it easy and quick to find a topic of interest.
Clicking on almost any link on the home page brings up a page designed like this:

Here, you learn there is a getting started guide. Why not put that link on the home page, instead of on each topics page?
Notice the crumb trail at the top left, which orients the visitor within the site and also serves as a navigation tool.
The Edit button on the top right is where the site’s content collaboration really gets interesting. That button opens a drop-down list of editing functions. From a tech writing perspective, the key ones are:

  • Edit –enables you to do three main things: 1) specify content issues by selecting from a pre-defined list of flags, 2) makes notes or comments, and 3) edit the page text. As an example, the Canvas screen above shows flags and comments made by one or more site users.
  • Edit Source—enables you to edit the mark-ups as well as the text.
  • History—displays a list of each version of the page, from which you can compare (that is, see the changes between) any two versions. Each version is identified with its creation date and author.

Although flags and comments appear on the page itself, content changes (and the users who made them) do not. This information is only available from the History command. Thus, any errors or ambiguities introduced by a user aren’t apparent to a new visitor. It would be helpful for edited pages to have a distinctive icon or other indication that they’ve been modified. (Users can select flags and leave comments without changing the text itself, so the presence of these editorial notations does not mean that anyone has changed the text.)
Finally, I want to mention a few technical issues. Registration is supposed to include a confirmation email but, at least when I registered, the email was not sent, so I had to manually request it before I was able to activate my login. When you do log in you should check the option “Remember my login on this browser (for a maximum of 180 days)”; otherwise, the site deactivates your login when you click to a new page. Last, the links to external sites open in the current browser window. A better practice is for the linked page to open in a new tab or browser, facilitating review and comparison between both open pages.
While we respect the fact that the site is in Alpha, there is still usability work to be done. As a beacon of what the future holds for useful documentation, navigation and user experience need to be given as much if not more attention than the technical content is. Hopefully the next version will address some of these issues. Have you explored the site at all? Please share your thoughts on usability and user experience below.

*Allen Brodsky is an award-winning technology writer with 15-plus years of experience creating user documents, web content, and marketing pieces for Fortune 100 and SMB technology firms. He has also conducted writing seminars for corporations and lawyers, and taught college courses on business and technical writing. Working from the New Jersey shore, he blogs at aTechWritingBlog.com. Connect with him on LinkedIn or email