During the Engagement team work week last week, the four on-staff Mozilla developer documentation writers (myself, Janet Swisher, Jean-Yves Perrier, and Will Bamberg) had a sit-down to talk. This was a big deal since it was Jean-Yves’s first time meeting with us in person since joining Mozilla on December 1, and Will’s first time meeting with us since he’s been largely off doing fairly separate stuff documenting the Jetpack SDK.
We had a long discussion about a wide variety of things, and I figured I’d blog about it, to share those ideas and thoughts with the wider Mozilla community — and to flesh out the ideas from the outline format I took the notes in.
Today, I’ll be sharing the results of our discussion about the impending Kuma migration and what will come next.
Scripts and templates
The next Big Thing that needs to happen in Kuma’s ongoing development process is to implement support for the type of scripted templates we use pretty frequently on MDN. One of my goals for when I resume work after this week I’m taking off (I do so love scheduled automated posting in WordPress) is to go through our existing templates and figure out the types of things we need to be able to do, to get those prioritized for the development team.
It’s almost certain that we’ll be using server-side JavaScript rather than the Lua-derived DekiScript language currently used by MDN’s MindTouch based wiki. That means we’ll need to update our existing templates. It’s possible some sort of automation might be done for that, but realistically, I don’t expect that to happen (and if it does, there will certainly be a need to review and hand-tweak stuff in at least some cases).
That said, this will be a great opportunity to look at all our templates, figure out which ones we don’t really use anymore, and get rid of them. In addition, we can clean up existing templates to work better, be smarter, and integrate localization support in templates that don’t currently have it.
Future development
We need to be ready for the future. The initial deployment of MDN on Kuma will not have all the features we want. Indeed, it won’t even have all the features we already have, although it should have most of the ones we use regularly. As such, we need to be sure we have bugs filed to give the development team a solid set of things to be done going forward.
Among other things, we’ll want to be able to have live examples embedded in documentation, so you can see how things work without having to click a link to a separate page. These should support HTML, CSS, JavaScript, and all the web goodness we love so much.
We need support for server-side components, so that examples for XMLHttpRequest, WebSockets, and the like can be run without needing to host stuff outside Mozilla’s servers.
We’d like features to make it easy to integrate documentation content with IDEs and other utilities, as well as to make it easier for scraping tools to peel out content to present in other formats.
We want offline access to the content, either by publishing sections of the site as PDF or by making it easy to download chunks of the site in HTML form.
We need good localization tools, such as dashboards of content in need of translating, support for comparing the English and translated versions of a page to find the areas that need reviewing, and so forth.
Let’s make it happen!
We’ll be making sure we have a prioritized set of features to guide the developers toward making Kuma a platform that serves our needs as well as possible. If you have ideas for features the Kuma platform could have to make our lives better, please share them.
This is our chance to have as near-perfect a platform for our documentation as possible! It will take time to get there, but we’ll do our best to make it happen!
