WPW Week 3: What type of contributor are you?

When I first edited a webplatform.org page, I was very nervous. I have experience (I won’t mention the number of years…) with both technical content and editing. So I expected to come to webplatform.org and dig into the content and change it easily. That wasn’t my experience. Whether it’s because of the MediaWiki markup or the expert eyes on the content or the instability of the site, I’m not sure, but I was intimidated. It didn’t help that just about the first contribution I made (after consulting with a couple of folks) was reversed by someone halfway around the world, in the middle of my night.

I’d consider myself a “Nervous Nelly” as they say. Or after that first experience, I’d call that contributor “Tim Idreget.”*

tim idregret_sm

Yes, that was me: timidly pushing ahead only to regret doing so. But that’s ridiculous. No one cared. I made an edit, someone thought it wasn’t correct and changed it back. Someone just as unfamiliar with the site as I was. Someone who wasn’t privy to our discussion around the table. Someone who was trying to get through the tasks he wanted to do.

But what to do? Change it back to my way? Play tug-o-war? Leave it quietly and walk away? What to do?

Ask Shepazu! And of course, that was the best, because he said – and I’m not quoting here, but something to the effect of – This indicates that one of you doesn’t understand what the other is doing. Send a query and get it cleared up. And I did and it did.

rip enburn_smBut that brings me to another type of contributor. Let’s call him Rip, Rip Enburn. His sense of self proceeds himself. He’s not concerned with the page’s history: who edited this when and exactly what did they do – who cares? He’s on a roll, taking no prisoners, going for speed, and all that. Fortunately, I haven’t come across any of these on webplatform.org. But they’re out there. As an innocent lamb, if some of your content has been ripped to shreds, follow up. Make sure you know why. Get a second opinion. Rip may, in fact, not be right, or have even noticed that he clobbered something – or someone – along the way.

OK, I have to say it. Although they will not be given a stage name, there’s another contributor that is hard to take. It’s the armchair contributor.
armchair contributor_sm

Named after the armchair philosopher, they observe, they postulate, they provide commentary, but they don’t edit the actual page! (There’s an interesting discussion on wikipedia.org about armchair philosophy under the heading “Armchair theorizing.” A more visceral definition can be found in the Urban Dictionary.)

And, to tell you the truth, I’ve been one of these myself. It’s so much easier to lie in wait for someone else to make a contribution, and contribute suggestions on how they contributed. I have been to “community” sites and said “this is really bad” or “just bad,” and even left a comment to that effect. But did I stick around to offer a solution or take it to a resolution?

At any rate, what I want to be – what I want for you to be – is a confident contributor, like Connie Fident. She has a lot of hands, because she can work so creatively and smoothly, always knowing what to contribute, and how, within just the right amount of time.

connie fident_sm

But, really the only way we’re going to get there is to actually edit the pages themselves, and share our experiences and help each other improve, and then edit the pages themselves.

Whatever type of contributor you are, please do join us this week as we continue to improve the Array object and its properties, function and methods. We’ve broken out some of the tasks involved with editing the basic facts. So let us know if that takes off the edge to editing a page. Or let us know what type of contributor you are and how we can improve the experience for you. Don’t be shy, just edit a page and let us know how it went by emailing the public list.

* Persons depicted herein are fictional and do not represent any real persons living or dead, except for Shepazu.

Fluent 2014 Doc Sprint (& You’re invited too!)

A group of us working on WebPlatform Docs will be hosting a Doc Sprint at Fluent 2014, in San Francisco, on March 11th! O’Reilly has generously provided the facilities and experts through the Fluent conference, but the doc sprint is open to the general public.

We receive content from various sources: companies, individual contributors, standards groups, and more. When we get the content, we review it, improve it, and add “that little something more.” For example, right now, we’re concentrating on JavaScript language reference content. A doc sprint is a period of concentrated effort by a number of people to improve that content, or really, any part of the site that you’d like to work on. It’s like a hackathon for documentation.

No experience is necessary! At a doc sprint, beginners can learn how to get started. We have some basic tasks that anyone can do with support. And we’ll be there to support all contributors. Folks with more experience can make great progress on deeper tasks. We’ll all collaborate on the site: extending it and building the content, itself. Bugs get fixed on the spot. We do usability testing. We eat and drink and… Well, doc sprints are great places to geek out, make new friends, and meet old ones. To get a sense of past doc sprints, check out our previous posts.

Just go to Eventbrite to sign up. We look forward to seeing you there!

WPW Week 1: Array

Here we are at Web Platform Wednesdays Week 1 for the JavaScript language reference! There’s a reason why organizations and individuals have come together to document the web platform here. The content can be used and reused anywhere, without complex terms. What you contribute is for everyone’s use. It’s sort of documentation neutrality. So while this may appear to be just another JavaScript reference that we’re embarking on, it really is different.

We’ve got the scaffolding down, thanks to Microsoft, but let’s add some magic — that special something that comes from giving a gift, unconditionally.

We’re starting with Array this week, focusing on the object, itself, the constructor, and those few properties that make Array a special object, such as length and isArray. When working with basic reference content, we have the opportunity to add some wise words (such as, unless there’s a reason not to, create an array using literal notation). And let’s up the ante with examples. What kinds of code helps you when you’re learning a new feature? What did you wish you knew back way back when you were starting with JavaScript?

There’s plenty to do, even if you’re not a JavaScript expert: check the values against those in the spec, make sure all of the content from the MSDN page were imported, or find great blog posts and articles. Join us this week as we get the facts down, provide clear information about the language, and share the magic. Check out the language elements and how the activities break down, then let us know what you want to do by emailing the public list.

Web Platform Wednesdays, meet JavaScript!

You’ve been waiting for a space to share your most treasured thoughts on JavaScript? Well, the wait is over. We’re ready for the second content project on webplatform.org. The JavaScript reference pages that Microsoft donated have been imported. That means we’re ready to make them ours! So, we’ll start up Web Platform Wednesdays again. There are about 350 language parts to review and improve.

Next week, we’ll have a list of JavaScript language elements that folks can add their wisdom to. We’ll publish the lists on Tuesday evenings PST, so that folks in Europe can start their Wednesdays with a fresh list.

Email the public list <public-webplatform@w3.org> with the pages you want to work on, and what you’re taking on (basic facts, explanations, samples, 3rd-party links…). If you’re interested in working on something not listed, no problem. Just let us know.

And if you’re particularly talented, we could use your help constructing what we call a gold standard page — an example that all other contributors can reference to see what we consider a great page. If you’re available now to work on a part of the gold standard, just email the public list <public-webplatform@w3.org> to sign up.

We’ll be live on the IRC channel #webplatform to help out on Wednesdays — we’re actually there a lot of the time — so join the channel and don’t be shy.

See you next week!

JavaScript reference docs land on WPD

The goals of webplatform.org are bold, its projects large and ambitious. As have many other volunteers before me, I caught a sense of that vision and decided to make it my own while working on a particular ambitious project: documenting JavaScript on Web Platform Docs.

I’m happy to say we’ve just completed a major milestone in documenting JavaScript on WPD. The first part of the project was to take JavaScript reference material donated by Microsoft and reformat and import it into Web Platform Docs, fitting it into templates and forms to make the content match the WPD structure.

I took charge of detailing the structure of the page content, and importing, normalizing, and converting the original HTML into wikitext, while in parallel Eliezer Bernart created the Semantic MediaWiki templates for each page. Eliezer started out knowing nothing about Semantic MediaWiki, but with enthusiasm and skill quickly learned how to build the templates and worked closely with me to create the framework to hold the content in a structured way. This kind of teamwork across nations and continents (Eliezer in Brazil, and me in North Carolina, USA) is what makes a project like this special.

Building a dream, making real what you have envisioned, and materializing ideas ultimately comes down to sharing your dream with people who will build with you, who are willing to take a series of smaller steps as their own. Though the contributors at WPD are divided across various projects, locations, and teams, we work under just enough guidance to aim in the same general direction. Your dream becomes the larger dream, and those smaller steps feel lighter and less difficult to the person fueled by a sense of accomplishment passing milestones of completion towards the building of what they deem good and useful.

Along with this dream came inevitable disagreements, volunteers whose hours don’t always coincide, people who have to go away a few weeks on another project before coming back to help, and other pesky irritations that are really the human backdrop every team has to face. It’s the nature of collaboration.

But this dream also meant making new friends: two people each driving halfway across a state to meet up and discuss the project, working with others who excel in their own area, feeling you are part of something bigger than yourself. Some contributors and colleagues to be called out by name include Doug Schepers, Eliezer Bernart, Eliot Graff, Julee Burdekin, Rick Byers, Rick Waldron, and Renoir Boulanger. I thank each person and am glad to have met you!

What this initial JavaScript import means is integrity and reliability of information, ongoing relevance as that information changes, and designers to improve its usability. Webplatform.org is not just another site, it’s a plan to building resources for a better web. This first phase created an initial corpus. We’ll follow this with additional work to attach additional semantic data, add topic clustering, generate automatic subpage listings, and best of all, enforce cross-checking with and cross-referencing to original ECMAScript standards. Keep checking this blog for announcements about how you can help with all this. Come catch the dream.