Vancouver documentation sprint recap

 Firefox, MDN, Mozilla, Writing  No Responses »
Apr 302013
 

Last night, I got home after another fun and productive MDN documentation sprint; this one was held in Mozilla’s lovely Vancouver office. In addition to Mozilla’s paid writing staff and a few core contributors, we had Mounir Lamouri, a Mozilla platform engineer, on hand to offer technical expertise about web-based device APIs. In addition, two Vancouver-area residents, Aras and Amr, also joined us, making their first contributions to MDN!

The MDN doc sprint team in Vancouver in April 2013.

Photo provided by Florian Scholz.

 

To top it all off, Vancouver-based content strategy expert Rahel Bailie dropped in to help us do a quick-and-dirty content strategy analysis; it was reassuring to discover that we’re more or less thinking along the right lines and on the right track in that regard.

Both virtual and in-person sprints have their pros and cons. Virtual sprints let people participate from anywhere without the need to travel and leave their normal lives and families behind. But in-person sprints give us the opportunity to have the kinds of conversations that work best when everyone’s in the same room together with a whiteboard. We had several of those conversations during this sprint in addition to documentation writing activities.

Conversations

Some of the whiteboard discussions we had during this sprint included:

  • We talked about the content and structure for the home page and global navigation of MDN. Expect to see these changes start to happen in the next few weeks!
  • A team met a couple of times to draft and refine a specification for the Localization Dashboard. This has been proposed as a Google Summer of Code project. Whether a student tackles this for GSoC or our own dev team builds it, having a spec is an important step.
  • We had a very long and engaging discussion about MDN’s page types and the elements they need. I will be turning our sketches and notes into a specification proposal this week.
  • We brainstormed ways to improve our involvement in events, whether they’re MDN doc sprints, other Mozilla events, or even external events.
  • We talked about our new process for managing documentation bugs by using the “Developer Documentation” component in Bugzilla along with Scrumbu.gs.

Documentation written

We also had lots of documentation written. I doubt this is an exhaustive list (in fact, I know that it isn’t), but it’s a list of what people specifically noted down that they worked on. Even as an incomplete list, this is a lot of great work. I’d like to thank everyone for their time and effort!

Aras Balali Moghaddam

Aras modified the following pages to make use of live code samples. We’re pretty excited about our live sample system, so getting more of them is always awesome!

Florian Scholz

  • Updated the MathML mspace element’s documentation per bug 717546.
  • Updated the methods of inlDOMUtils per bug 839443.
  • Updated the documentation for document.createElement() for bugs 851916 and 844127.
  • Updated the documentation for table.insertRow() and tableRow.insertCell() for bug 824116.
  • Created documentation based on several code bugs marked dev-doc-needed.
  • Updated MathML compatibility information on reference pages to note that Chrome has completely removed MathML support.
  • Moved MathML pages into the new hierarchy (Web/MathML and Mozilla/MathML_Project).

Eric Shepherd

  • Added a section about media presentation to Firefox OS apps tips and techniques.
  • Updated the docs for nsINavHistoryService to fix bug 703893.
  • Updated the docs for JS_SetGCZeal to note a signature change in Firefox 14, per bug 787723.
  • Created the template APIListAlpha for producing alphabetical lists of subpages as pretty indexes.
  • Started work on building the hierarchy for the new open Web documentation structure, including the Web landing page and the Web APIs page.
 Posted by at 2:18 PM

Sprintime in Vancouver

 Firefox, Geekology, MDN, Mozilla, Writing  No Responses »
Apr 252013
 

Ah, spring! The flowers bloom, the snows melt (usually), and lovers of the Web and of Mozilla are heading to Vancouver, British Columbia to participate in our spring documentation sprint at the Vancouver Mozilla Space.

We’ll be gathering writers and a few developers together to pound out as much great documentation as we can, along with, I’m sure, a few fun evening activities.

If you can join us, feel free to drop in! Or participate virtually by logging into MDN and joining the chat in the #devmo IRC channel. We’ll save a seat for you at the ol’ keyboard.

 Posted by at 8:13 AM

MDN platform (Kuma) news

 Firefox, MDN, Mozilla  No Responses »
Apr 082013
 

There’s been a great deal going on on the Kuma front of late. If you’re not already aware, Kuma is the Mozilla-built wiki platform that powers the Mozilla Developer Network (MDN) documentation. Today, I’m going to share a few tidbits about what the team is up to and what’s coming in the near future.

New Features

We have some new features! Let’s take a look!

  • You can now specify a maximum depth for tables of contents on individual pages. Say you have a page that has lots of repetitive sub-headings. You can keep those from exploding the length of the TOC now. Just open the “Edit Page Title and Properties” pane in the page’s editor, and you can now specify how deep the TOC should be allowed to get (or disable it entirely, as before).
  • You can now add a revision comment when saving new articles; this can be especially useful for people like me to note things like “just getting started, more to come,” for example.
  • Admins now have a “View in Admin Panel” option to look at a page in the Django admin panel; this gives us access to the option to delete a page, for example, saving precious time and hair-tearing-out.
  • Unused bits of data are no longer displayed in revision diffs and page history. We used to show some information that we inherited from SUMO but don’t actually use.
  • The page footer now includes a link users can follow if they’d like to contribute to the Kuma project.

Back-end Improvements

We’ve also done more work on improvements to the internals, structure, and so forth. This includes work on upcoming new features that aren’t exposed to users yet. Some of the more interesting ones:

  • Upgraded to Django 1.4.5.
  • Upgraded to jQuery 1.9.1.
  • The CSS for our custom fonts has been updated to allow the fonts to be cached locally instead of having to be re-downloaded all the time.
  • A number of bits of optimization work have been done to help improve page load times and the like.

Bugs Fixed

  • You can now use the title attribute on <div> blocks.
  • Several other minor bugs have been fixed.

As you can see, the team has been busy. Now that the bulk of the back-end work on the Elastic Search and Django upgrades has been finished, the team is moving on to other things (although the front-end work on ES is still ongoing). I hope to see some really good new stuff arrive soon.

Coming Soon

Work has begun on designing and hopefully soon implementing the notification system that will be used by our review queue as well as by page watchlists. Once we have that system, a lot of awesome new features will become possible, and we’re really excited to have that work underway!

Also, section editing is gradually making progress. I hope we’re in the home stretch on finally being able to edit individual sections instead of having to edit the entire page every time we want to make a simple tweak.

The guys are working hard, and I’m very proud to work with them! Thanks guys!

 Posted by at 11:14 AM  Tagged with:

Mozilla Developer Network docs team news

 Firefox, MDN, Mozilla  2 Responses »
Apr 052013
 

We have a lot going on these days! Obviously, Firefox continues to surge forward, with new features all the time. That alone would keep us busy, and indeed it does. Jean-Yves Perrier has been heading up Firefox developer documentation work for the last couple of months, and I expect he’ll keep doing so for the foreseeable future.

Of course, there’s more than just Firefox. The developer tools team has been cranking out amazing new tools to help Web developers (and, in turn, Firefox OS developers), and those need lots of documentation work. Will Bamberg has taken over that work from me, since I’ve been completely swamped lately. This fits in well with the work he’s already been doing with the Jetpack documentation, since many of the same people are involved.

Mark Giffin, working under contract (although he’s been working with us so long, it’s hard to think of it that way!), has been working hard on the open Web apps documentation. This documentation obviously plays a key role in our plans for Firefox OS, and it’s great to have him pounding away at that.

Janet Swisher has been so busy for so long being “distracted” away from writing by her work organizing doc sprints and other community activities that it’s in the process of becoming official; she will become our MDN community manager (although I’m not sure precisely what title is involved). She’ll be working full-time on building our developer community and helping to organize events. This is going to be fantastic to have someone doing that for real, and I know Janet will continue to do it well — especially once it’s her “real” job!

In the meantime, I’ve been sliding more and more into organization work. There are two kinds of organization involved.

Content organization. I’ve been working, gradually, on rearranging content on MDN to be more logically structured. The Web apps documentation has been rearranged, as has much of the WebAPI documentation. In addition, I have cleaned up the structure of the Firefox OS content as well. This work will continue for some time, but it’s a relief to finally be making some amount of headway. We have big plans for rearranging the so-called “DOM Reference”. For details, you can see the article Web platform documentation hierarchy.

Team organization. As the MDN docs team has grown — both in terms of paid staff and in terms of our awesome army of volunteers — it’s become more difficult to keep up with what’s going on. This is, of course, exacerbated by the fact that we have so many projects to work on. So going forward, more of my time is going to be spent organizing and coordinating the writing team. I’ve been doing a lot of writing about documentation processes, and gradually we’re nailing down plans for ways to improve how we do things.

One thing you should expect to see soon is pages you can visit to see what each team member is currently working on, as well as a list of upcoming documentation projects and their status.

I’ll be blogging more soon specifically about the organizational work we’re doing, once the actual plan documents are finished and posted onto MDN.

In addition to organization, I’ve been working on the MDN Style and User Guide documents. These suites of documents will help us bring new contributors into the fold, and will help us produce better, more consistent documentation in the future. On top of all that, the style guide is going to be used to help inform the design team as they work on designing the next generation UX for the MDN web site. The new design is going to be spectacular, but only if we participate in the process.

I’ll blog more about this once these documents are farther along; however, one thing you can look at and help with right now is the MDN page types list. This article is meant to list all the basic kinds of pages we have on MDN, and to list the features each needs to offer. Eventually this will be detailing each type of page all the way down to which visual styles are needed in order to construct them, so that the design team knows what CSS we will need. This information will also be used to help us build better toolbars and to improve the editing experience in general, so if you have frustrations with editing on MDN, this page is a place you should go and contribute to!

So that’s what we’re up to, in brief.

 Posted by at 12:46 PM

Requesting developer documentation, the easy way

 Firefox, MDN, Mozilla  1 Response »
Jan 312013
 

As part of our effort to improve our documentation process, we now have a Bugzilla form that makes it easy to provide the proper information we need in order to handle a request for documentation. In addition to offering guidance as to how to fill out the form, fields that we don’t need (or need to have specific values) aren’t presented, and are handled automatically on your behalf.

If you find yourself often requesting the addition of (or changes to) documentation on MDN, you should seriously bookmark the new form:

https://bugzilla.mozilla.org/form.doc

The new form looks like this:

Screen shot of the new documentation request form

The Request Type indicates whether you’re asking for new documentation or a correction to existing materials. The Topic drop-down menu offers a list of topic areas (DOM, HTML, JavaScript, etc.) to help categorize your request. It’s helpful to specify a technical contact; this is the email address of someone that knows about the topic so that the writers can find someone quickly to help answer questions. This field supports lookups from Bugzilla’s user database, to help you get it right the first time.

The Development Bug field lets you enter the bug number of a bug that should be blocked by this documentation request. That lets us monitor the development process as well as to locate people that may know more about the topic to be documented.

The Urgency field lets you indicate how quickly the documentation request would preferably be handled. The default is “No Rush,” but there are options to indicate that the docs are tied to a given stage on the release train, as well as an “Immediately” option for emergency documentation updates.

It’s important to note that we make no guarantees as to how quickly documentation will be written. There’s a lot to write, and there aren’t that many people to do the writing, so sometimes even important things will sit around and wait for a while.

 Posted by at 7:00 AM

Love Firefox? Love writing? Read on!

 Firefox, Geekology, MDN, Mozilla, Writing  10 Responses »
Dec 172012
 

Given our ongoing documentation-needed overload, we’ve decided to look into contracting out some writing work to help catch up our Firefox developer documentation. Basically, we’ve not been able to keep up with our Firefox X for developers documentation (see Firefox 17 for developers, for instance). While stuff gets listed, the list is often not complete, and even where items are put on the list, they’re usually not actually documented.

This is, frankly, embarrassing.

However, the staff writers, and even most of our community of writers, have been very busy with Firefox OS and other documentation, leaving Firefox itself rather strapped for attention. That’s got to change.

So the other day, I talked to Ali (my boss) and we agreed that we should see about contracting someone to go through all of these documents, from Firefox 13 onward, and get them fully up to date, and try to document the technologies and changes as needed.

There are some skills required:

  • You need to be proficient in JavaScript — at least well enough to read code without needing a lot of help, and to throw little snippets together as needed to demonstrate new features.
  • Likewise, you should be competent with HTML and CSS, at least well enough to sort things out without hand-holding.
  • If you have experience reading the IDL that describes DOM interfaces, that’s a big help, but we can help you figure it out (it’s not hard).
  • You should feel comfortable talking to developers by email and in IRC. You’ll have questions and being able to interface with these guys will be a huge help.

You won’t be in this alone, of course. Our existing community of writers hangs out in #devmo on irc.mozilla.org and we’ll be there to offer encouragement, advice, and some help.

If you’re interested, let me know. We haven’t opened up this contract yet, but I’d like to start getting a handle on who might be interested, so I can have a list of possible candidates ready to go once that happens.

This is important work that’s sadly fallen by the wayside due to limited resources and conflicting priorities. Help us make the Firefox developer documentation excellent again!

 Posted by at 1:01 PM

Using the MDN revision dashboard

 Firefox, MDN, Mozilla, Writing  No Responses »
Dec 052012
 

One of the relatively new features on MDN’s Kuma wiki — and one that’s still a work in progress — is the Revision Dashboard. This dashboard presents you with a list of the most recently changed articles, and lets you review those changes. Although the dashboard isn’t yet linked to from the UI on the MDN wiki, it’s there. We’ll add a link to it soon; we have some UI decisions to make first.

The dashboard page consists of three sections: the filter section, the revision list, and the revision diff.

Filters

At the top, there are filtering options.

Screen shot of the filter list

You can choose to filter by locale, if you’re interested only in changes in a given locale. By default, you get all locales, but often you’re only interested in changes in your language (or in English if you’re looking for new stuff to translate). In addition, you can filter to find recent changes for a specific user. You can specify these filters in the URL, as well. For example:

Revision list

The revision list is (surprisingly enough) a list of article revisions. Each row in the list corresponds to one edit to an article. The article’s locale and title are listed, as well as the date of the revision, the username of the person that made the change, and any comment they added when saving the article.

Screenshot of the article list

Clicking on a revision in the list displays the revision’s diff and additional options; with these, you can revert a change (thereby making the version of the article prior to the selected one current), view the page, open the page in the editor, or view the page’s complete history.

Clicking on an article’s title will open that article so you can read it in all its glory. Clicking a username filters the current list to only show changes made by that user.

Revision diff

After you’ve clicked on an article revision, the Revision Diff area shows a diff of the HTML, so you can see what changed in that revision of the article.

Screen shot of the diff area

Viewing the actual article may be handy when reviewing more complex diffs, since it can be hard to gauge what exactly changed when looking at the raw HTML source.

Expect change!

The revision dashboard is undergoing ongoing development, so expect it to look different from time to time. In fact, I’m already seeing mockups of it looking rather different (and better!) than this in several ways. But the core functionality is there. Expect change, but it’ll be great change!

 Posted by at 11:44 AM

Want to make MDN better but not much of a writer?

 Firefox, Geekology, MDN, Mozilla  2 Responses »
Dec 032012
 

The Mozilla Developer Network (MDN) is (and yeah, I may be a little biased here) one of the greatest online resources for Web developers you’ll find online. We’re constantly writing away, trying to make it better, and if you haven’t seen me (or one of our other team members) out there trolling for more people to write documentation, you’ve probably not been paying attention. Which is fine — because maybe you’re not much of a writer, or you prefer to hammer away at code.

As it turns out, there’s more to MDN than writing prose explaining how things work. Here are a couple of things you can do to help out if you’d like to make MDN better but find writing in languages other than C or JavaScript tedious and frustrating!

Make the documentation platform better

MDN uses our very own, open-source, Kuma wiki platform to power its documentation. We’re hard at work to make the software better, with our fabulous and hard-working development team pounding out code at ludicrous speed.

That said, however, there are plenty of things on our development team’s to-do list, and some help is always welcome. In addition, maybe you have an idea of your own!

The Kuma code is available on Github. Feel free to pull it and see what you can do. There are instructions available for how to set up your build environment, as well as for how to contribute to the code.

If you’d like to talk with the development team, get help, and even talk with the writers that are most engaged with the development process, feel free to pop into the #mdndev channel on IRC. You can also keep an eye on what the rest of the development team is up to by checking out their status updates on our Standu.ps site.

Sample code

A key feature of any developer documentation is good sample code. While we have some sample code, we can always use more. Until recently, adding samples was not always easy, especially if you wanted people to actually be able to see what the code does. However, with the recent addition of our live inline sample support, that’s all changed for the better.

Feel free to peruse our documentation and find places where samples would be useful and devise some! Obvious candidates for live samples are the HTML and CSS documentation, as well as documentation about DOM interfaces and functions. You can probably also come up with some helpful examples for the JavaScript docs, too.

Examples don’t have to be fancy or flashy. Indeed, the simpler they are, the better, in most cases. The less extra “stuff” there is for the reader to have to deal with, the more quickly they can get to the heart of the matter and really understand what they’re looking at.

Help me, Coder-wan Kenobi… you’re my only hope

There’s a ton to do! Between documentation (that’s where the writing community comes in), the Kuma project (where our Kuma dev team, hopefully including you soon, comes in), and samples (where, well, everyone comes in!), there’s plenty to be done. There’s something out there for everyone. Can you find your perfect place to contribute to help make the best online resource for Web developers even better?

 Posted by at 1:38 PM

MDN virtual doc sprint starting November 30!

 Firefox, Geekology, MDN, Mozilla, Writing  1 Response »
Nov 152012
 

We’re having a virtual — that is, online — MDN documentation sprint from November 30 through December 1! We encourage anyone interested in helping make documentation of and for the open Web to log onto #devmo on irc.mozilla.org and help out. Even if you only have a few minutes, it’s possible to make a huge difference. Indeed, if you’re a Web developer that knows lots of things, you can log in and help answer questions the writers might have. That’s a way you can contribute to MDN content without doing any writing yourself!

Check out the wiki page about this doc sprint and put your name on the list if you plan to participate. There’s even a list of links to suggested topics for work. And you can even contribute by simply adding live samples to existing articles, using our nifty new live sample system!

I hope to see you there! We always have a good time and get lots of great work done to make developing for the open Web easier for everyone!

 Posted by at 7:30 AM

Kuma update: November 14, 2012

 Firefox, MDN, Mozilla  No Responses »
Nov 142012
 

That’s right! We have another, small, update to the Kuma software on MDN today. This is a really small update that corrects a bug in yesterday’s push, and has a chunk of code that’s disabled right now anyway.

  • Fixed the Live Sample boilerplate button to insert code with the correct class names. You can now use the Live Sample system without having to use source mode to correct the mistake.
  • Tweaked the backend code for the live sample system to be less picky about the class name strings’ content.
  • Added some backend code for the revisions dashboard; this is part of the upcoming support for filtering the contents of the list there. However, it’s disabled right now, so there’s no user-discernible impact.

For more information about using the live sample system, read the documentation for it on MDN. We’re all really excited about the live sample system. This is a feature we’ve wanted for ages (literally since back when I first joined Mozilla). So I’m thrilled that Louis-Rémi Babé came up with this technique (and wrote an initial proof of concept that showed it would work), and with Les Orchard and David Walsh for building the system. Thanks, guys!

 Posted by at 12:58 PM  Tagged with:
 Older Entries  Newer Entries