Aug 222014
 

This week looks slower than usual when you look at this list, but the week involved a lot of research.

What I did this week

  • Reviewed and made (very) minor tweaks to Chris Mills’s doc plan for the Gaia web components and QA documentation.
  • Created an initial stub of a page for the canvas documentation plan.
  • Spent the weekend and a bit of Monday getting my broken server, including this blog, back up and running after a not-entirely-successful (at first) upgrade of the server from OS X 10.6.8 Server to 10.9.4. But most things are working now. I’ll get the rest fixed up over the next few days.
  • Pursued the MDN inbox project, trying to wrap it up.
    • Asked for feedback on the current state of things.
    • Added a subtle background color to the background of pages in the Inbox.
  • Started discussions on dev-mdc and staff mailing list about the documentation process; we’re going to get this thing straightened up and organized.
  • Filed bug 1056026 proposing that the Firefox_for_developers macro be updated to list both newer and older versions of Firefox.
  • Redirected some obsolete pages to their newer, replacement, content in the MDN meta-documentation.
  • Created a Hacker News account and upvoted a post about Hacks on canuckistani’s request.
  • Updated the MDN Administration Guide.
  • Installed various packages and add-ons on my Mac and server in preparation for testing WebRTC code.
  • Forked several WebRTC projects from GitHub to experiment with.
  • Found (after a surprisingly length search) a micro-USB cable so I could charge and update my Geeksphone Peak to Firefox OS 2.0′s latest nightly build.
  • Re-established contact with Piotr at CKSource about continuing work to get our editor updated and improved.
  • Removed a mess of junk from a page in pt-BR; looks like someone used an editor that added a bunch of extra <span>s.
  • Successfully tested a WebRTC connection between my Firefox OS phone and my iMac, using my Mac mini as server. Now I should be ready to start writing code of my own, now that I know it all works!
  • Filed bug 1057546: we should IMHO strip HTML tags that aren’t part of a string from within a macro call; this would prevent unfortunate errors.
  • Filed bug 1057547 proposing that the editor be updated to detect uses of the style attribute and of undefined classes, and present warnings to the user when they do so.
  • Fixed a page that was incorrectly translated in place, and emailed the contributor a reminder to be careful in the future.

Meetings attended this week

Monday

  • MDN dev team meeting on security and improved processes to prevent problems like the email address disclosure we just had happen.
  • MDN developer triage meeting.

Tuesday

  • Developer Engagement weekly meeting.
  • 1:1 with Jean-Yves Perrier.

Wednesday

  • 1:1 with Ali.

 Thursday

  • Writers’ staff meeting.

Friday

  • #mdndev weekly review meeting.
  • MDN bug swat meeting.
  • Web API documentation meeting.

So… it was a wildly varied day today. But I got a lot of interesting things done.

 Posted by at 6:16 PM
Aug 162014
 

I’m quite satisfied with how well the past week has gone. It’s been incredibly productive despite a few distractions and a great many meetings. Here’s my report on what I’ve been doing, and what I will be doing in the near future.

What I’m up to

I’ve been busy optimizing my own work processes, as well as setting up information so others know what needs to be done as well. I’ve also done a lot of copy-editing and organizational work in content, and have been touching up stuff ranging from the MDN inbox to the Learning Area to doc plans. It’s been a wonderfully productive week, and it feels good to be getting back into the swing of things.

What’s up next

Next week, I intend to dive into WebRTC, and to start putting together sample code so I can begin work on writing guides to working with WebRTC. It’s going to be really exciting!

As usual, of course, I have a number of other, smaller, tasks I want or need to accomplish, too.

What I did this week

  • Moved the main page on DocShell from the top level of MDN to its proper home, and filed a bug on getting it fully documented.
  • Dealt with infrastructure failures at my office: the air conditioning completely failed (working in a swelteringly hot office is not fun), and I discovered standing water in the restroom. The A/C is now fixed; the water problem has not been figured out yet, although the water has evaporated for now.
  • Helped test the new GitHub login support on the MDN staging server, and filed a few bugs regarding quirks I noticed.
  • Reviewed and had nothing but nice things to say about the new welcome email sent out by MDN to new members.
  • Got involved in the discussion about disabling styled pasting in the MDN editor. I’m opposed to this; I would much rather we solve the problem from the user’s end — contributors should learn to be sure they don’t include crufty styles when they paste into MDN. But ideally we can come up with a solution that doesn’t break existing workflows, punishing people who aren’t making this mistake.
  • Moved the page Write a new entry in the Glossary to the right place; it had accidentally been given an obsolete URL due to a couple of MDN bugs. Reviewed and copy-edited the content.
  • Filed a bug for a feature suggested by biraj: content from one page on MDN that’s presented inside another page should be reflected in the displayed contributor list. I don’t know how likely this is to be addressed (it certainly won’t happen soon). It’s a big project and there are many unanswered questions.
  • Copy-edited the new Glossary entry for the term “i18n“.
  • Added the word “Glossary” to the list of tags that MDN offers auto-completion for.
  • Followed-up on a bug asking me to write some copy for the Github login experience.
  • Did some tidying up of the MDN style guide, including moving Chris Mills’ excellent new section on our policies on gender-neutral terminology to be among the language and grammar topics rather than in the markup and wiki usage topics area.
  • Minor changes to the Learning Area page on CSS. This page needs a lot of work still but I saw low-hanging fruit.
  • Converted the Learning Area into a zone. Its landing page needs finishing, but this is a nice step.
  • Finished an extensive review and copy-edit of the Learning Area page Write an article to help learn about the web.
  • Removed a page that was actually just a set of Firefox problem reports, and emailed the author information about how to properly report issues.
  • Found an MDN “Linking Guide” lurking in a dead part of the site, and moved it into the MDN user guide, with major updates and copy-edits.
  • Updated the MDN user guide’s landing page to use the LandingPageListSubpages macro, so it looks a little better.
  • Adapted Luke’s screenshot/diagram about how to enable a page subscription on MDN into a new page in the MDN how-to guide.
  • Tweaks to the Inbox page in preparation for expanding its visibility.
  • Integrated the first round of feedback into the WebGL documentation plan.
  • Updated my Geeksphone Peak to Firefox OS 2.0 nightly for use in upcoming WebRTC sample code tests.
  • Filed a bug about iCloud.com saying “Android not supported” on Firefox OS 2.0′s browser.
  • Pinged developers about reviewing the WebGL documentation plan.
  • Created several new basic (that is, mostly empty) MDN development project plan pages:
  • Copy-edited the Learning Area’s How to contribute to the Learning Area article.
  • Filed a documentation request bug for documenting the NavigatorFeatures (hasFeature/getFeature) API. This API is low-priority privileged API, documentation-wise.
  • Added notes to a couple of pages in the MDN contributor guide about being careful when pasting, to avoid pasting unwanted styles and classes into MDN.
  • Created the DocPlanHelpUs macro, which inserts text inviting participation in a project and describing how to get started. Added it to the appropriate place in all extant doc plans.
  • Took some notes, sent some emails, and added links to the project planning page for the on-site messaging project.
  • Added a link to the MDN contributor guide to the footer of messages on the dev-mdc mailing list, and tweaked my email address on the moderator email list names.

Meetings attended this week

Monday

  • #mdndev bug triage
  • MDN development planning

Tuesday

  •  1:1 meeting with Jean-Yves

Wednesday

  • MDN Community meeting
  • 1:1 meeting with Ali

Friday

As you see, it was an intensely busy week! I’ve started moving into using OmniFocus to track what needs to be done and by when and I think it’s going to help, but we will see how it plays out over time. I have a history of not doing well at keeping up with my organizational systems, as you’ve possibly noted if you read my posts over history about my various attempts to get organized.

At any rate, it’s been a good week, and I can’t wait to get more done!

 

 Posted by at 12:07 AM
Aug 082014
 

It’s been another good week of Making Things Happen. I’m pleased with the productivity this week: not just mine, but the entire writing community’s.

What I’m up to

As usual, what I did this week doesn’t entirely line up with what I’d expected, but it was still productive, which is the important thing, right?

Work continued on finishing up the doc project planning page migration work, and better integration with other pages on MDN and elsewhere. I also put together the first draft of the WebGL doc plan.

I’m working on trying to reshuffle my many personal appointments that happen regularly to less often interfere with meetings, but unfortunately there’s only so much I can do.

What I did this week

  • Replaced the main documentation plan page on wikimo with a link to the new page on MDN, with an explanation of why it moved.
  • Finished work on moving the Learning area doc project plan to MDN.
  • Migrated the “Writing chrome code” doc plan to MDN, then emailed Will Bamberg to let him know his planning docs had moved.
  • Wrote first draft of the WebGL doc plan and emailed dev team to request feedback.
    • Got quick feedback with WebGL 2.0 ship date and added that information to the doc plan.
  • Added the dev-doc-needed keyword to man WebGL 2.0 related bugs.
  • Filed a bug about a problem with the link editor not suggesting zone pages that have moved out of the /docs/ hierarchy.
  • Added a link to the WebRTC doc project plan to the WebRTC documentation status page.
  • Posted to the dev-media list asking for suggestions on topics to cover in the WebRTC docs.
  • Updated the MDN page about KumaScript macros to link to the new article on troubleshooting them that Stephanie Hobson wrote.
  • Did a quick copy-edit pass on the troubleshooting article, and added some information about how to use search keywords to get to macro pages quickly (to read the built-in documentation most have).
  • Emailed out various meeting reminders.
  • Updated the team priority list spreadsheet with updated URLs and new information.
  • Wrote agenda for writers’ staff meeting and Web API docs meeting.
  • Wrote a nifty new MDN macro, ContentFromWikimo, which imports the content of a specified block (by ID) from a page on wikimo and inserts it into the MDN page.
  • Used the ContentFromWikimo macro to embed module owner information about WebRTC, WebGL, Web Workers, and XPCOM to their doc plans.
  • Filed a number of meta/tracking bugs for the various doc plans.
  • Created meta/tracking bugs for all current documentation plans. See my standup for today for links; I’m not going to copy and paste them all here. :)

Meetings attended this week

Monday

  • #mdndev bug/triage/planning meetings.

Tuesday

  • Messaging discussion for MDN feature planning.

Wednesday

  • 1:1 meeting with Ali.

Thursday

  • MDN writers’ staff meeting.

Friday

  • MDN development bug swat meeting.
  • Web APIs documentation meeting.

So, whew! Lots done! I’m particularly proud of the ContentFromWikimo macro work. It was also a lot of fun to do. I think it’ll be useful, too, at least sometimes.

I have a good feeling about next week. I think it’ll be even more productive!

 Posted by at 1:47 PM
Aug 012014
 

It’s been a while since my last Sheppy Report; there several good(ish) reasons for that. I won’t rehash all that today, though.

My intent is to resume these weekly reports; they were well-received back then, and I hope they’ll help improve my ability to keep people apprised of what I’m doing and about what’s new on MDN.

What I’m up to

My primary mission this week was to work on the MDN documentation project plans, getting them prepared for use by moving them to MDN, building any necessary content and macros  to support their presence, and so forth. This has gone pretty well, although it’s not quite finished yet. I plan to work on Saturday to complete this project.

Next week, I intend to tackle integration of the project plans with doc status pages and to write the WebGL documentation project plan. This will let us get started with the job of finding someone to write that important content.

There’s plenty more on my to-do list, and it’s possible priorities could shift, but finishing the current work is pretty much my Most Important Thing right now.

What I did this week

  • Created the landing page for the new home of MDN documentation project plans.
    • We decided to move these planning documents to MDN (even though planning docs don’t traditionally belong on MDN) in order to integrate them with our processes better. Having them on MDN means we can use KumaScript to automatically populate tables from bug lists, other areas of MDN, and so forth.
    • This will also let us integrate them with our existing doc status page system, which has been a great tool. I look forward to this augmentation work.
    • This page automatically rebuilds every four hours so its macro-generated list of subpages can be kept up to date.
  • Archived our old “Team Status Board” page. This was an experiment in tracking what individual MDN contributors were working on that didn’t work out.
  • Updated the non-standardGeneric macro
    • Corrected a typo that broke the macro, causing a KumaScript error on all pages using this macro or one that calls it.
    • Improved performance slightly by adding code to bounce out of loops when an end condition is detected early.
  • Migrated the developer phone documentation project plan to MDN, reformatting it to follow the new organizational structure for these plans.
  • Copy-edited the string.repeat() documentation.
  • Rewrote parts of the MakeColumnsForDL macro on MDN; this macro, which breaks up a <dl> into two columns for our landing pages, was in some cases splitting the list in the midst of a <dt> tag.
  • Migrated the Game Developer Zone documentation project plan to MDN.
  • Created a framework doc plan page for the RecRoom project.
  • Created a framework doc plan page for the WebGL docs project.
  • These framework doc plans will require filling -out, of course.
  • Corrected an accidental “translation-in-place” incident that replaced the English Apps zone landing page with Italian.
  • Created the <picture> element doc plan page on MDN.

There’s lots not covered here, such as email catch-up from my vacation a week or two ago, and all sorts of non-meeting discussions about MDN features, ideas for improving articles, etc. But you’re likely not interested. In fact, I bet you didn’t actually read this far anyway. :)

Meetings attended this week

Monday

  • #mdndev planning meeting
  • #mdndev pull request triage
  • MDN bug triage
  • Mozilla staff meeting

Tuesday

  • Developer Relations town hall meeting

Wednesday

Thursday

  • One-on-one meeting with Jean-Yves
  • Employee training meeting

Friday

  • One-on-one meeting with Ali

Unfortunately, a personal meeting ran very long on Friday, causing me to miss several scheduled meetings. Repeat apologies to everyone affected.

In general, a pretty productive week. A lot got done, and I’m making definite progress.

 Posted by at 6:12 PM
Jun 112014
 

I’ll be attending the Open Help Conference & Sprints event this weekend, arriving in Cincinnati on Friday afternoon and returning home on Tuesday morning after the first day of documentation sprinting. Mozilla is a proud sponsor of this event, which features a number of key influencers in the open source documentation arena. The mission: to exchange notes and ideas about how to improve the quality and quantity of good open source documentation, and to hold documentation sprints to get some writing projects done.

I’ll be giving a talk on Saturday morning (at 10 AM—the first presentation of the event) entitled “Help people so they can help you.” I’ll be covering the things the MDN team does to build, foster, and support its growing community of contributors. I’m looking forward to this, even though I’m nowhere near prepared yet. I enjoy sharing ideas about how to create and maintain excellent documentation. It’s my career’s mission, and as a Mozillian, I’m pleased to be able to share. Hopefully, too, I’ll get new ideas this weekend as well!

As an aside, if you have any thoughts on things I should be sure to mention, don’t hesitate to leave a comment or drop me an email!

If you’re going to be at Open Help, or are simply in the Cincinnati area, I hope to run into you!

 Posted by at 9:51 AM
Mar 292014
 

There’s been something of an uproar over Brendan Eich’s promotion to the role of CEO of Mozilla Corporation due to the fact that many years ago, he donated money to support Proposition 8 in California. I’m not going to link to any of the blog posts, tweets, or news stories about this, since I don’t really want to give more traffic to rumormongers, especially since a lot of the stories are mostly speculation.

Since I work for Mozilla, I obviously have opinions on this. I’m going to share them, but first I’m going to be sure to point out what I’m not:

  • I’ve never reported to Brendan either directly or indirectly.
  • I’m not gay, so his opinions in the area don’t directly affect me.

With that out of the way, let me say this: in the more than eight years I’ve worked at Mozilla, I’ve never known Brendan to treat anyone differently based on their gender, sexual orientation, color, religion, eye color, height, weight, or anything else (sorry for being slightly flippant there; it’s how I handle this stuff).

I felt then, and feel now, that Prop 8 is a mistake, is unconstitutional, and is a moral catastrophe. Freedom to marry the consenting adult of your dreams is a core human right and should be protected as such. Now with my feelings on the matter exposed, let’s press on.

While I, too, would like him to make a statement clarifying things further, I also don’t think it’s any of my business. As long as Brendan’s feelings don’t impact his work functions, I honestly don’t care what he thinks. As far as I can tell, all he cares about is whether or not you can deliver the goods when you’re working on the project. That’s all that matters to me.

He can be cranky and dismissive at times when he thinks you’re wrong (or less right than he is), but everyone can be that way (I know I can). Whatever his personal feelings are on gay marriage (or homosexuality in general, or anything else), Brendan is a brilliant developer and manager, a great leader, and an avid supporter of open source software and of the free and open Web. In those respects, he’s the best possible person for the job of CEO of Mozilla.

Mozillians are a diverse community. Brendan knows that; he’s known that since he first helped create Mozilla a decade and a half ago. He’s never once been involved in controversy related to that diversity; becoming CEO doesn’t, I think, make him any more likely to be so.

Let’s give him the benefit of the doubt, and get back to rockin’ the open Web.

 Posted by at 4:04 AM
Feb 212014
 

The most important rule of contributing to the developer documentation on MDN is this:

Don’t be afraid to contribute, even if you can’t write well and can’t make it beautiful. It’s easier for the writing team to clean up information written by true experts than it is to become experts ourselves.

Seriously. There aren’t that many of us on the writing team, even including our awesome non-staff contributors. We sadly don’t have enough time to become experts at all the things that need to be documented on MDN.

Even if all you do is copy your notes onto a page on MDN and click “Save,” that’s a huge help for us. Even pasting raw text into the wiki is better than not helping at all. Honest!

We’ll review your contribution and fix everything, including:

  • Grammar; you don’t have to have perfect (or even good) writing skills—that’s what the writing team is here for!
  • Style; we’ll make sure the content matches the MDN style guide.
  • Organization; we’ll move your content, if appropriate, so that it’s in the right place on the site.
  • Cross-linking; we’ll add links to other related content.
  • Structure and frills; we’ll ensure that the layout and structure of your article is consistent, and that it uses any advanced wiki features that can help get the point across (such as live samples and macros).

It’s not your job to make awesome documentation. That’s our job. So don’t let fear of prevent you from sharing what you know.

 Posted by at 10:15 AM
Feb 182014
 

A key aspect to the documentation process is communication. Not only is the completed documentation itself a form of communication, but thoughtful, helpful communication is critical to the production of documentation. For the MDN documentation team to create content, we need to be able to interact directly with the developers behind the technologies we write about.

Today I’d like to share with you how that communication works, and how you can help make documentation better through communication. Not only do we need your help to know what to document, but we need information about how your technology, API, or the like works. The less time and effort we have to put into digging up information, the sooner we can have documentation for your project, and the better the coverage will be.

Pro tip: Assume we know nothing about your project. We don’t know who you are, what your technology is or does, or even that it exists. If you start with that assumption, and provide all the information you have, everyone probably wins.

Share details

There is basic information we will almost always need when working on documentation for an API or technology. If you’re proactive about providing this information, it will save everyone time and energy. I mentioned this previously in my post about writing good documentation requests, but it bears repeating:

  • Who are the responsible developers? We will almost certainly have questions, and nothing slows down a writing project like spending two weeks trying to figure out who can answer simple questions.
  • Make sure we have links to the specifications and any design or implementation notes available for the project. We probably will find the specification on our own, but anything beyond that is likely to be missed. And if you send us the spec link (which you probably have memorized by now anyway), you’ll earn our appreciation, which can’t hurt, right?
  • Where’s the code for your implementation? Providing a link (or links) to the code tree(s) on mozilla-central and/or Github can save us tons of time, since we will refer to the code often while writing.
  • When the specification and/or design is finalized, let us know! We usually won’t start writing until the design has settled down into a reasonably stable state, and if we don’t know it’s stabilized, we might never get started. Similarly, if there’s an unexpected change after the specification was supposedly finished up, be sure to ping us then, too!
  • Do you have code samples or snippets? Sharing links to those, or to any tests you’ve written, can help us understand how your API or technology works—and it gives us a head start on writing example code for the documentation.
  • Do you have a schedule? Let us know when you expect to hit your milestones and when you expect to reach each branch.

Looping us in

The more your team is able to integrate the documentation team into your docs process (and vice-versa), the better. It’s actually pretty easy to make us feel at home with your team. The most important thing, of course, is to introduce your project to the writer(s) that will be working on documenting it.

To find out who will most likely be writing about your project or API, take a look at our topic drivers list on MDN. If you’re unable to figure it out from there, or don’t get a reply when you ping the person listed there, please feel free to ask me!

  • Invite us to attend any planning or status meetings for your project. Don’t assume we know about them (we probably don’t, unfortunately). Being able to listen in on your meetings (and occasionally even offer suggestions) is incredibly helpful for us. We see a lot of APIs, and you never know, we might have ideas you can run with.
  • Be sure we know what mailing list or mailing lists your team has discussions on. We will probably either want to become regular readers or at least be able to quickly pull up archives while doing research.
  • Let us know what IRC channels we should hang out in to participate in discussions about your project or the technology you’re working on.
  • Do you have work weeks? Invite us to join you! Having a writer attend your work week is a great opportunity to interact and get some face-to-face discussion in about the documentation, what you need, and what you’d like to see happen.
  • Whenever someone blogs about the project, technology, or API, let us know. Don’t assume we’ll see it go by on Planet, because odds are very good that we won’t. Ideally, you should add a link to it to your documentation request bug, but at least email us the link!

Join the conversation

We will almost certainly be having discussions about the documentation work you need from us! It’s often helpful for you to be proactive about being engaged in those discussions. It’s always best to get your input, requests, and suggestions sooner rather than later.

  • If your project is large enough, we might start having meetings specifically to discuss its documentation work. This type of meeting is typically short (our Web APIs documentation meeting has never run longer than 20 minutes, for example). We will invite you to attend these, and we’d love to have you, because it’s a great way for you to comment on documentation quality, priorities, and the like.
  • You’re welcome to join us in #mdn, the IRC channel in which we discuss documentation work, if you want to chat with us about specific documentation concerns or questions, or if you want to make a fix or addition yourself but need some advice.

Useful resources

There are a few additional useful resources on MDN that can help to improve the interaction between the writers and the developers for a project:

 Posted by at 12:44 PM
Feb 142014
 

Over the last few days, I’ve provided lots of information about what types of documentation MDN features, how to file a documentation request, and so forth. Now I’d like to share some tips about how to file a documentation request that’s clear and provides all the information the docs team needs in order to do the job promptly and well.

While adding the dev-doc-needed keyword to bugs is a great start (and please do at least that, if nothing else), the best way to ensure your documentation is produced in a timely manner is to file an actual documentation request.

Note: See also my older blog post about the documentation request form; that post is a tad out of date but may also be interesting/useful.

Ask early

The sooner you ask for documentation to be written, the better. Even if you haven’t started to actually write any code, it’s still not too early to file the documentation request! As I’ve mentioned in previous posts, the sooner we know that we may need to write something, the easier it is to nudge it onto our schedule when the time comes. This is both because of easier logistics and because we can ensure we’ve been following the status of your project and often can start research before it’s time to start writing.

As soon as you realize that documentation may need to be written—or updated—file a documentation request!

Write a useful summary

The bug summary should at a minimum mention what APIs or technologies are affected, and ideally will offer some insight into how out of date any existing content is or what Firefox release incorporates the changes. Some good examples:

  • Update FooBar API documentation for Firefox 29 changes
  • Document new interface nsISuperBar added in Gecko 33
  • Document that document.meh method deprecated in Gecko 30, removed in Gecko 31
  • Note in docs that WebSnickerdoodle support brought into line with WebKit implementation in Gecko 28
  • Docs for WebPudding say it’s unsupported in Blink but it is starting in Blink 42

Some bad examples:

  • Docs for WebGL suck
  • Update all docs for Gecko 42
  • Add documentation for <some word that doesn’t match the name of any spec/technology mentioned anywhere on the Web>

Be sure to use the right names of technologies. Don’t use your nickname for a technology; use the name used in the specification!

Where are existing docs?

If you know where the existing documentation for the material that needs updating is, include that information. Obviously, if you don’t know, we won’t make you hunt it down, but if you’re already looking at it and shaking your head going, “Boy, this is lame,” include the URL in your request!

This information goes in the “Page to Update” field on the doc request form.

Who knows the truth?

The next important bit of information to give us: the name and contact information for the person or people that can answer any questions the writing team has about the technology or API that needs documentation work. If we don’t have to hunt down the smartest person around, we save everyone time, and the end result is better across the board.

Put this information in the “Technical Contact” field on the doc request form. You may actually put as many people there as you wish, and this field does autocomplete just like the CC field in Bugzilla, using Bugzilla user information.

When does this change take effect?

If you know when the change will take effect (for Firefox/Gecko related changes, or for implementing open Web APIs in Firefox), include that information. Letting us know when it will land is a big help in terms of scheduling and in terms of knowing what to say in the compatibility table. This goes in the “Gecko Version” field in the doc request form; leave it “unspecified” if you don’t know the answer, or if it’s not relevant.

If you don’t provide these details, we’ll ask for it when the time comes, but if you already know the answer, please do provide as much of this as you can!

On a related note, providing links to the development bug which, upon closing, means the feature will be available in Firefox nightly builds is a huge help to us! Put this in the “Development Bug” field on the doc request form.

Be thorough!

Provide lots of details! There’s a lot of other information that can be useful, and the more you can tell us, the better. Some examples of details you can provide:

  • A brief explanation of what’s wrong (for problems with existing documentation), or what needs to be written.
  • A link to the specification and/or design documents or wikimo pages for the feature.
  • Relevant IRC channels in which the technology is discussed (for example, if it’s a gaming API, you might remind the potential writer to ask about it in #games).
  • Links to blog posts that the dev team(s) have written about the feature/technology/API. These are a great source of information for us!
  • Link(s) to the source code implementing the feature/technology/API.
  • Link(s) to any tests or example code the dev team has written. We use these to help understand how the API is used in practice, and often swipe code snippets for our on-wiki examples from these.
  • Target audience: does this technology/API impact open Web developers? App developers? Both? Only Gecko-internals developers? Add-on developers? Some other group we haven’t previously imagined? Green-skinned aliens? Tortoises?

Wrap-up

I hope this information is useful to help you produce better documentation requests. Not just that, but I hope it gives you added insights into the kinds of things we on the documentation team have to consider when scheduling, planning, and producing documentation and documentation updates.

The more information you give us, the faster we can turn around your request, and the less we’ll have to bug you (or anyone else) to get there.

We know Mozillians love good documentation: hopefully you can help us make more great documentation faster.

 Posted by at 4:26 PM
Feb 102014
 

On Friday, I blogged about how to go about ensuring that material that needs to be documented on the Mozilla Developer Network site gets taken care of. Today, I’m going to go over how you can tell if something should be documented on MDN. Believe it or not, it’s not really that hard to figure out!

We cover a lot on MDN; it’s not just about open Web technology. We also cover how to build and contribute to Firefox and Firefox OS, how to create add-ons for Firefox, and much more.

A quick guide to deciding where documentation should go

The quick and dirty way to decide if something should be documented on MDN can be summed up by answering the following questions. Just walk down the list until you get an answer.

  • Does this information affect any kind of developer at all?
    • If the answer is “no,” then your document doesn’t belong on MDN, but might belong on SUMO.
  • Is the information about a technology that has reached a reasonably stable point?
    • If the answer is “no,” then it may eventually belong on MDN, but not yet. You might want to put your information on wiki.mo though.
  • Is the information about a Web- or app-accessible technology, regardless of browser or platform?
    • If “yes,” then write about it on MDN!
  • Is the information about Mozilla platform internals, building, or the like?
    • If “yes,” then write about it on MDN!
  • Is the information about Firefox OS?
    • If “yes,” then write about it on MDN!
  • Is the information about add-ons for Firefox or other Mozilla applications?
    • If “yes,” then write about it on MDN!
  • If you get to this line and haven’t gotten a “yes” yet, the answer is probably “no.” But you can always ask on #mdn on IRC to get a second opinion!

A more detailed look at what to document on MDN

Now let’s take a more in-depth look at what topics’ documentation belongs on MDN. Much of this information is duplicated from the MDN article “Does this belong on MDN?”, whose purpose is probably obvious from its title.

Open Web technologies

It should be fairly obvious that we document any technology that can be accessed from Web content or apps. That includes, but isn’t limited to:

Important: It doesn’t matter if these technologies are implemented by Mozilla. Indeed, we even document technologies that are non-standard and only implemented by other browsers (case-in-point, we document a number of WebKit-specific CSS properties). All that matters is that the technology or API is exposed to any content on any browser or platform.

This also includes APIs that are specific to Firefox OS, even those that are restricted to privileged or certified apps.

Firefox OS

An important documentation area these days is Firefox OS. We cover this from multiple perspectives; there are four target audiences for our documentation here: Web app developers, Firefox OS platform developers, developers interested in porting Firefox OS to new platforms, and wireless carriers who want to customize their users’ experience on the devices they sell. We cover all of these!

That means we need documentation for these topics, among others:

  • Open Web apps
  • Building and installing Firefox OS
  • Contributing to the Firefox OS project
  • Customizing Gaia
  • Porting Firefox OS

The Mozilla platform, Firefox, and add-ons

As always, we continue to document Mozilla internals on MDN. This documentation focuses primarily on developers building and contributing to projects such as Firefox, as well as add-on developers, and includes topics such as:

  • Gecko
  • XUL
  • XPCOM
  • Building and configuring Firefox
  • Add-ons (extensions, plug-ins, and themes)

What don’t we cover?

There’s one last thing to consider: the types of content we don’t include on MDN. Your document doesn’t belong on MDN if the answer to any of the following questions is “yes.”

  • Is it a planning document?
  • Is it a design document for an upcoming technology?
  • Is it about a technology that’s still evolving rapidly and not yet “ready for prime time?”
  • Is it a proposal document?
  • Is it a technology that’s not exposed to the Web and is specific to a non-Mozilla browser? If it’s not exposed to the Web, but is part of Mozilla code, then you just might want to document it on MDN.

Wrap-up

Hopefully this gives you a better feel for the kinds of things we document on MDN. If you learned anything, I’ve done my job.

Over the next few days, I’ll be continuing my blitz of documentation about documentation process, how to help ensure the work you do is documented thoroughly and well, and how to get along with writers in general.

 Posted by at 4:57 PM