Editing experience

The editing experience is going to get some improvements. First, the switch to CKEditor will be made as the default editor. They’re also making improvements to the toolbar to make things clearer. For example, the style drop-down menu will have checkmarks to indicate which style or styles are in effect.

The tagging interface will also be improved, with a cleaner UI and better skinning support. In addition, initial foundation will be laid for managed tags; that is, support for limiting users to a predefined set of tags. This will help keep our content better organized.

Content templates

Real page templates will be provided; when creating a new page, a dialog box will appear to let the user choose what type of page they’re adding. These templates will be configurable, and could include, for example:

• Blank page
• API reference index
• API reference page
• FAQ page

Content management

Content ratings

A new content rating system will be added; each article will offer a thumbs-up/thumbs-down voting system to allow users to indicate whether or not the article was helpful.

If the user rates the story thumbs-down, a popup will allow them optionally to comment on why they did so, to help editors update the content. Reports will be available to get insight into the readers’ opinions of articles, what sorts of activities occur on articles, and so forth.

Search results will also include a box next to each item indicating the quality score for each article (ie, if 3/4 of people rated it thumbs up, you’ll see “75%”).

Contributors will be able to view a content dashboard, which will show the site’s worst-reviewed articles as a way to triage content that needs work.

Page title/Move functionality

Currently, the way page titles are handled is a little confusing, especially when handling moving or renaming pages. Some changes will be made to reduce this confusion.

The page’s title will now be edited in a separate edit box, outside the body of the article. Articles will have separate titles from their “permalinks.” Both can be edited from the same box, but the UI will let you easily choose whether to only affect the displayed page title or the permalink. You’ll also be able to only change the permalink, although that’s not something I think we’ll do often.

User pages

The User page is getting something of a revamp, with support for user dashboard widgets. These will provide views of information the user may find useful, such as:

• A list of the user’s recent changes
• A list of subscriptions or watchlists with recent activity
• Comments sent by other users
• A “notes” area for jotting down notes
• A “task list” area for keeping simple to-do type lists
• A list of pages with low ratings that are tagged with keywords indicating they overlap with the user’s area of expertise.

That last bullet is especially interesting. Users will be able to use their user page to say, “I’m good at JavaScript, XPCOM, and extensions,” and the wiki will match them to content that needs work, recommending articles they could take a look at and try to improve. This is a huge, huge win for us, and something that I think we’ll be able to take major advantage of in the future.

These widgets should be easy to develop plug-ins for, which will let us further improve the usefulness of the user pages; additionally, these dashboard boxes may be supported elsewhere on the site as well.

Additionally, user pages will no longer be treated as equals to “real” content pages during searches; content on user pages won’t show up mingled with the site’s actual documentation. This will keep notes and work-in-progress stuff out of end users’ way.

Also, when new users sign up, they will no longer automatically get a User: page created for them. It will only be created when the user actually starts configuring it. This will save a lot of space in the database, since a lot of users never actually touch their user page.

Search

Search is getting an overhaul too. Better results will be paired with improved user control over the display of the results.

• Users will be able to filter the namespace (ie, all content, documentation only, user namespaces)
• There will be support for add-on modules to enhance search; for example, we could add a plugin so the MDC search on the wiki would also search blog posts or other content.
• The user will be able to sort the results by user rating, article creation date, or article modification date. This lets them look for top-rated content, or most-current content, for example.
• The language filter should actually, finally, work reliably.
• An RSS feed link will be provided so you can get an RSS feed that will provide those search results.

Administrators will be able to “promote” articles; that is, they’ll be able to say “This article is definitive about its subject,” so that the article will get “bumped” in search results.

Search analytics

Also, search analytics will be available, allowing documentation curators to review what search terms people are looking for, as well as information on whether or not the user actually found what they wanted (that is, if they actually clicked any links on the results page).

This will let us improve search results by discovering articles that aren’t getting scored properly based on, for example, not using key words in their bodies. Some of our older articles, for example, frequently abbreviate “JavaScript” as “JS”, which would prevent them from being indexed well for searches on “JavaScript”.

We’ll also be able to see lists of the most popular search terms, terms that led to follow-up searches (that is, someone does a search, doesn’t find what they want, and refines their search terms to try again).

These analytics will also be used by curators to promote and demote pages to affect their placement in search results. We can take older, obsolete articles and demote them so they show up lower in search results, without actually having to remove them from the site to get them out of the way.  This will vastly improve our ability to maintain historical content without confusing readers.

Extensibility

Along with support for custom widgets, mentioned previously, MindTouch plans to make it possible to add new Special pages using DekiScript instead of having to use PHP plug-ins. This will further make it easier for us to add features to the site, especially reporting features and the like.

Wrap up

Whew! That’s a lot of stuff. As you can see, the meetings and discussions I’ve been having with MindTouch around usability and documentation management have been extremely fruitful. I think this work, and the follow-up releases to come afterward, will make our lives much better.

The obvious remaining concern is performance. Once we get MindTouch 9.12.2 installed — we’re testing now — we should see a noticeable performance and stability gain. Here’s hoping!

This opens up a lot of possibilities for extension developers, by making it vastly easier to interface with native libraries. This includes support for directly talking to system APIs.

The demo I’m working on is an extension for Mac users that adds an item to the context menu that appears when you right-click on images, “Add image to iPhoto.”

I’m using Core Foundation routines and the Launch Services API, which is part of the Application Services framework to implement this, by taking the URL from the img element’s src attribute, grabbing that, and using Launch Services to open it in iPhoto.

The trick at the moment is that I need to pass a reference to a standard, built-in structure that’s part of the Core Foundation framework to a Core Foundation routine, and at the moment, js-ctypes doesn’t support accessing these external structures. But dwitte has a patch for that, and we’re testing that patch now, so that barrier should be lifted shortly.

With that done, hopefully I’ll be able to wrap this demo up soon, then I can work on updating the existing js-ctypes documentation, which was written to an older version of the API. While the existing docs are mostly still accurate, they only cover a fraction of the current capabilities of js-ctypes.

The past week or so of working on this has been a blast. I really enjoy when my code monkey side and my documentation overlord side collide like this. It’s great fun, and, as in this case, often leads to discoveries that are helpful to the engineers behind the feature being documented.

In this case, we found a viable use case for needing to implement support for accessing external data provided by libraries. We also found a situation in which not being able to catch exceptions thrown by the external libraries can be a problem (ie it can bring down your browser), so there’s now a bug filed for that.

Also, the errors reported by js-ctypes still need some love, so there’s a bug for that now.

Also, there are cases where it would be very helpful for clarity’s sake — and for implementing things such as the concept of a CFMutableArrayRef being passable to any function that accepts a CFArrayRef — to support const declarations.

This is one of those times where being a technical writer feels especially full of win. My work toward understanding a technology has resulted directly in improving the technology itself. That reeks of awesome, and makes my job all the more worth doing.

Do you enjoy teaching people how to make awesome stuff happen?

Do you have great writing skills and a knack for figuring out how stuff works by looking at the code?

Want to make the Web a better place for everybody?

If so, you’re in luck! Mozilla is now looking for a great writer to help make the documentation on the Mozilla Developer Center even better. Keeping up with the rapid pace of growth of Web technology is exciting and hectic, but extremely rewarding.

If you’d like to take a shot at making the Web better, maybe you should apply for our new Technical Writer: Developer Documentation position!

The “[doc-waiting-1.9.3]” note means that the issue isn’t expected to land until Gecko 1.9.3. This doesn’t necessarily mean it won’t be documented until then, it’s just to help me prioritize work, since for obvious reasons stuff that’s in Gecko 1.9.2 is my top priority right now.

“[doc-waiting-info]” is used so that I can easily see that I’ve already looked at an issue and have asked one or more questions that need to be answered before I can write the material up. This will help me avoid spending a lot of time looking at the same bug over and over again before I actually have the necessary information to write it up.

“[doc-waiting-landing]” is used to mark items that have a patch, but it’s unclear on which branch the code will be checked in (or if it will be at all). Again, this helps me avoid looking repeatedly at items that aren’t ready to write about yet.

I’m sure I’ll have more of these in the future, but I wanted to explain my usage of these in case any of them seemed confusing, and to point out that they don’t necessarily mean super-long delays getting stuff written about (especially in the “[doc-waiting-1.9.3]” case).

I mention this periodically in several forums, but it can’t be said often enough, so here we go:

First, if there’s a bug related to your work, make sure the “dev-doc-needed” keyword is added to the bug in Bugzilla. It doesn’t matter if you’ve actually made the change or not. The writers only apply changes to the documentation once the bug is both tagged as “dev-doc-needed” and the bug is marked as fixed. Until then, we pretty much ignore it.

Second, make sure the change that impacts developers is clearly explained somewhere in the bug comments. If necessary, add a new comment that explains what’s changed and why it’s relevant to developers, or at least says “Comments X, Y, and Z are relevant to developers.” This will reduce the likelihood that we’ll have to hunt people down and ask a lot of questions in order to ensure that the stuff gets written up adequately.

Third, if there isn’t really a good bug in Bugzilla on what needs to be written, feel free to file a new bug against the Mozilla Developer Center’s Documentation Requests component, explaining what needs to be written up. Useful information here includes links to the files that have changed (especially IDL), multiple relevant bugs, etc.

In all cases, including information about who would best be able to answer questions about the topic would be extremely helpful.

You can pretty safely assume that if your material isn’t either tagged as “dev-doc-needed” or filed as a bug against MDC, it won’t get written about. The sooner either of these is done in the development cycle for a given release, the more likely you are to get good documentation written, because this helps me schedule writing work to ensure that there’s time allotted for everything.