Nov 222011
 

One problem we’ve had for some time now is that due to a quirk in how the MindTouch software MDN is currently using for its wiki, when a user that isn’t logged in clicks a link to a page that doesn’t exist, they’re rather unhelpfully rerouted to the MDN home page. This is obviously suboptimal, but we’ve never had a solution.

Late last week, I was listening to my daughter read a book to me when a possible (partial) solution popped into my head (why at that time remains a mystery for the ages).

The Solution

On Friday, I spent some time coding up a few tests, which worked even better than I expected, and yesterday and today I’ve been putting my idea in action. I thought I’d share my solution, since it needs to be applied specifically when links are generated by templates. This doesn’t cover all cases, but does cover a lot of them (probably even most of them).

Those of you familiar with how we do things on the documentation wiki are probably aware of the templates such as Template:Interface, which generates a link to the appropriate page in the interface reference given the name of an interface. It intelligently looks for the interface given the old and new hierarchies of interfaces in our docs (since some older docs haven’t been moved yet), and builds the link on the fly, as well as applying appropriate styling to the text.

This is well and good unless the interface’s documentation hasn’t been written yet, in which case you get a link to a page that doesn’t exist, resulting in the problem I mentioned above.

My solution, which works for any automatically-generated links generated by templates updated to support this new mechanism, involves an intermediate template that can be used when pages don’t exist, as well as a page that actually does the rendering of a special new “article not found” page, which looks something like this:

Screenshot of the article not found page

This is what appears at present for a link generated by {{interface(“nsIJumpListShortcut”)}}. This offers some particularly handy features. First, it explains that the page doesn’t exist. Second, it prompts the user that if they’d like to log in, they can create the new page. Clicking the “Log in” link will provide a log in screen, which, when filled out, then immediately takes the user into the editor for the target page.

Third, it offers a link to search MXR (it says LXR but it’s really MXR) for the ID “nsIJumpListShortcut”. This search is performed on mozilla-central.

Fourth, although not seen here, the new system lets templates specify the URL of a specific file on mozilla-central; if specified, that URL is offered as another option.

The log in and create the page option is always provided; the other options are provided if the relevant information is passed to the new Template:NotFound template.

Using the Not Found System

Using the new “not found” system actually doesn’t directly involve using the NotFound template; instead, upon detecting that a page doesn’t exist, you create a link to the Article not found page, with query terms providing the parameters needed. The “Article not found” page converts the query terms into a call to theĀ NotFound template for you, thereby providing a standardized interface to the code. There are three query terms you can provide:

  1. “uri”: The local URI of the page the user tried to visit; this should be /language/path/to/article, with spaces replaced with underscores.
  2. “ident”: The identifier on MXR to offer to search for; if you don’t provide one, no MXR search is offered.
  3. “source”: The sub-path on mozilla-central of a file to offer a link to; for example, this might be “xpfe/appshell/public/nsIAppShellService.idl”. If you don’t provide this, no file link is offered.

In general, you won’t use this directly. Instead, templates should be updated to use it whenever possible. I’ve already updated the following templates to use the new not found system:

  • interface
  • ifmethod
  • HTMLElement
  • XULElem
  • XULAttr
  • XULProp
  • XULMeth
  • XULMeth2
  • MathMLElement
  • SVGElement
  • cssxref
  • domxref

I’m certain there are other templates that would benefit from being updated, but this is a good start. While I was at it, I tidied up a few bugs in some of those templates, mostly related to case-sensitivity problems. I hope this is as helpful as I think it will be! If you want to help update any existing templates, don’t hesitate to ask if you run into problems.

 Posted by at 3:44 PM
Nov 162011
 

Here are today’s Wiki Wednesday articles! If you know about these topics, please try to find a few minutes to look over these articles that are marked as needing technical intervention and see if you can fix them up. You can do so either by logging into the wiki and editing the articles directly, or by emailing your notes, sample code, or feedback to mdnwiki@mozilla.org.

Contributors to Wiki Wednesday will get recognition in the next Wiki Wednesday announcement. Thanks in advance for your help!

JavaScript

Thanks to Panagiotis Tsalaportas and berkerpekasg for their contributions the last couple of weeks.

SpiderMonkey

Developing Mozilla

Extensions

XUL

XPCOM

Interfaces

Plugins

CSS

Thanks to berkerpeksag for contributing!

SVG

HTML

DOM

Thanks to BYK and berkerpeksag for contributing since last time!

 Posted by at 3:13 PM
Nov 102011
 

If you’re contributing content to MDN related to WebKit’s implementation of open web features, there are a few handy things you should be aware of. The first: be sure to read over my previous post about documenting the open web on MDN, since it offers a lot of insight into how we’re trying to structure our documentation, as well as some information about our future plans to improve the site’s support for making this even easier.

Even more usefully, we’ve been gradually building out templates to help make it easier for you! We have a lot of templates that do things specific to Firefox, and we’re trying to either genericize those or add new ones for other browsers. WebKit has gotten special attention since our friends at Google have been contributing some great content, but we welcome folks to create templates for use when documenting support of open web features in other browsers as well.

The two templates for WebKit writers I’m going to mention today are WebKitBug and unimplemented_inline_webkit.

WebKitBug inserts a link to a bug in the WebKit bug database. This makes it easy for writers to add annotations to documentation to guide developers to information about things that are works in progress in WebKit. You use it like this: {{webkitbug(42)}}, and the result is “WebKit bug 42″, linked to the corresponding bug in the bug database.

Similarly, unimplemented_inline_webkit inserts a small, inline box with an optional link to a WebKit bug, given its bug number. If you write {{unimplemented_inline_webkit()}}, you simply get a box that says “Unimplemented”. More usefully (and preferred) is the syntax {{unimplemented_inline_webkit(42)}}, which inserts a box that says “Unimplemented (see WebKit bug 42)”, with a link to the bug.

Obviously this is just a beginning! I’d love to hear suggestions on ways we can further improve this, either by changing existing templates or by adding new ones. Feel free to follow up with comments here, or chat with me in #devmo on IRC.

 Posted by at 8:33 AM
Nov 082011
 

As you work on Mozilla, you’ll often file bugs or submit patches that will involve changes needing to be made to the documentation on MDN. I’ve written an article on MDN about this issue, and I’m duplicating it here to get it in front of more people that need this information.

Flag your bugs

When you file a bug that, upon resolution, will likely require that documentation be updated, you should add the dev-doc-needed keyword to the bug:

dev-doc-needed.png

You don’t need to wait until the bug is fixed. Indeed, it’s easiest for the doc team if you add this keyword well in advance of the bug being resolved. That lets us plan ahead. That said, it’s never too late to apply dev-doc-needed to your bugs!

Also, note that if you use the addon-compat keyword to flag that a bug will impact add-on compatibility, you should absolutely also add dev-doc-needed!

The writing team uses Bugzilla queries, as well as a special documentation tracking site that interfaces with Bugzilla, to track our work. By using dev-doc-needed, your bugs will get brought to our attention at the right time to ensure the best odds that your stuff will be written up in a timely manner.

When the bug’s contents are documented, the person that did the work will replace the dev-doc-needed keyword with dev-doc-complete and, ideally, add a comment to the bug with links to the pages that were updated or created to cover the bug’s contents. You should try to review the changes to ensure that the writer got things right.

Indeed, if you love Mozilla, you’ll be sure you’re available to help out if the writer has questions. They may contact you by email, or post questions as comments on the bug. Try to take a few moments out of your busy day to answer questions.

Provide information to the writers

That brings us to the next point. Not only should you be sure to answer questions the writers bring to you, but a little simple preparation can stave off a lot of back and forth. Try to add a note to the bug that indicates exactly what needs documenting. A lot of bugs have pretty cryptic descriptions, or the actual documentation issue at hand isn’t obvious from the bug’s description.

For example, a bug might have a summary like “foobar.com doesn’t work in Firefox 45″. There may then be pages and pages of comments where the problem is debated, possible solutions suggested, and so forth, followed by the bug eventually being marked as resolved. With no other information, the hapless writer is left to pore over all those comments and the patches, hoping to figure out what needs documenting.

When the patch is finally checked in, you should try to add a comment that summarizes what the final resolution was. This can be either “Writers: check out comment 32″ if there’s already a comment that explains the final resolution, or a quick summary of what’s changed, like “Check out the new method and attributes in nsISomeInterface” or “We added the someStandardDOMMethod” method to DOM elements”. Doing this can save the writers a lot of time (time that could better be spent writing even more stuff), and can save you from having to answer pesky questions.

It’s also helpful, of course, if your bug includes a link to the specification or design document for the feature being affected by the patch.

Just having directions on where in the code to look, or what subtle change has occurred, can make all the difference between your change being documented quickly and having it languish for a long time because it scares the writers off.

What if there’s not a bug for it?

Sometimes, you notice something’s wrong with the documentation. Maybe there’s a missing article, or you realize we need a guide on how to use some technology, and there doesn’t seem to be one. You can, of course, write it yourself. But if that doesn’t work for you, feel free to file a bug against the Documentation Requests product on the Mozilla Developer Network component on Bugzilla.

Feel free to update the documentation yourself

MDN is a wiki! You can log in and update the documentation yourself. A lot of programmers don’t consider themselves up to the task of writing documentation, or are crazy busy, and that’s okay! That’s why we have writers, and that’s why we have all the above tips.

However, if you have a few minutes, and feel comfortable doing it, feel free to log in and apply the necessary fixes yourself. This is often really simple for minor changes to the behavior of something, and can possibly save everyone time and effort.

For that matter, if you have the time to jot down relatively thorough notes about your change, you can toss them into the bug, or add them to the wiki. Our happy, helpful documentation gnomes live to clean up your writing, so don’t be afraid to try.

Ask for help!

If you’re not sure how to get something handled in documentation, or are trying to update the docs and are stuck, feel free to pop into #devmo on IRC, where the doc team hangs out, or ask questions on the documentation newsgroup.

 Posted by at 8:15 AM
Nov 072011
 

One of our initiatives on the Mozilla Developer Network’s documentation wiki is to improve browser agnosticism. That is, to ensure that where appropriate, our open web documentation is just as useful for web developers using other browsers as it is for those using Firefox. A lot of our documentation is currently very Firefox-oriented, even when it’s not necessary.

Consider this, for example:

Example of non-agnostic docs

Here we see a big banner about how this method of the DOM Element object was introduced in Gecko 1.9.1. However, it’s actually a standard DOM method. This banner should go away, and the text should be updated wherever necessary to remove any Firefox-specific discussion.

In addition, the article should have our standard browser compatibility table at the bottom. This table provides information about which releases of all the major browsers introduced support for the feature.

I’ve updated this article now so it looks the way it’s supposed to, as an example of what it ought to look like.

Noting introduction of sub-features

Some features are fairly complex; for example, the HTML <input> element has evolved over time, with the addition of new attributes and new possible values for many of them. This is where adding additional rows to the browser compatibility table comes into play. Let’s look at a few rows from the compatibility table for <input>:

Example of longer compatibility table

Here we see multiple table rows, each for a given named feature of the element being documented. In the case of Firefox, we see that type=color isn’t implemented yet, and we used {{unimplemented_inline(547004)}} to include a link to the corresponding bug. We also have the WebKitBug template for linking to WebKit bugs, and should add an unimplemented_webkit_inline or similar for creating Unimplemented badges that link to WebKit bugs, but haven’t done so yet.

Browser version-specific notes

Sometimes, you simply have to note browser-specific stuff, even in open web documentation. This should usually be done in the “Browser compatibility” section, with a subsection added for each browser that needs a note. For example, the browser compatibility section on the main WebSockets page has a subsection entitled “Gecko notes,” which covers Gecko-specific issues related to WebSockets, such as the fact that the constructor is prefixed.

If you do need to include browser-specific content in the middle of article text, try to put it in a call-out box or note box instead of just throwing it into the body text of the article.

The future

As we continue to build our Kuma, our new wiki platform for MDN documentation, we’re keeping browser agnosticism for documentation in mind. We have features planned to make it easier to call out browser differences and browser specific features, and to help readers filter the content based on their interests.

When in doubt… ask!

While updating or writing open web documentation, if you run into something that you’re not sure how to handle, please feel free to pop into #devmo on IRC, or to drop email to me, and ask for help. All of our happy, helpful documentation gnomes live to serve.

 Posted by at 2:04 PM
Nov 022011
 

Here are today’s Wiki Wednesday articles! If you know about these topics, please try to find a few minutes to look over these articles that are marked as needing technical intervention and see if you can fix them up. You can do so either by logging into the wiki and editing the articles directly, or by emailing your notes, sample code, or feedback to mdnwiki@mozilla.org.

Contributors to Wiki Wednesday will get recognition in the next Wiki Wednesday announcement. Thanks in advance for your help!

JavaScript

Thanks to BYK for contributing to these docs since last time!

SpiderMonkey

Developing Mozilla

Extensions

XUL

Thanks to Neil Rashbrook for his contributions!

XPCOM

Thanks to Neil Rashbrook for even more contributions!

Interfaces

Thanks again to Neil Rashbrook for his continuing contributions!

Plugins

CSS

Thanks to BYK for contributing.

SVG

HTML

DOM

 Posted by at 4:49 PM