Doc Sprint at beyond tellerrand has been a blast!

Last week another Adobe-hosted Doc Sprint with 53 attendees out of 70 registered happened. According to our Doc Sprint Dashboard the event resulted in over 800 edits to the wiki, got about 10 new contributors on board and smoothly transitioned over to the official warm-up-party for the famous beyond tellerrand conference in Düsseldorf, Germany.

We had an awesome time!

While the original plan had been to run the event in a beach bar setting, lacking a beach bar we ended up under an old gas station from the 50s. Nevertheless, the deck chairs specially made for this event (no leftovers – sorry!), as well as a delicious barbeque and volumes of free beer (and other drinks) made a sunny and comfy location to spend all day. Some people even got sunburned; others sent us thanks for an unexpected tan. :) (And there are many more fun bits and stories to tell. Check out some of them over at the Adobe Web Platform Team blog post on the event.)

The Location of our Web Platform Doc Sprint @btconf Düsseldorf, May 2014 - an old gas station from the 1950s

The Location of our Web Platform Doc Sprint @btconf Düsseldorf, May 2014 – an old gas station from the 1950s

Sun, fun, plus quite a bit got done

With the help of our community experts we split up the party into six focus groups as follows:

The HTML Elements focus group was led by Paul Verbeek and, most of the time, consisted of 4 people: Aaron Gustafson, Horia Dragomir, Michael Kühnel, and Paul, himself. The group documented a total of 33 elements and also made decisions on what to do with deprecated elements (= document them, stating it’s deprecated and why, and write in the past tense). Find their tracking sheet here.

The JavaScript focus group, led by Rodney Rehm, worked on the Number object. The group has put together a number of considerations and suggestions. Make sure to read through their detailed work output here.

Rodney Rehm shares the joy :o) on the work output of his focus group. Passion anybody?

Rodney Rehm shares the joy on the work output of his focus group. Passion, anybody? (Picture by Andreas Dantz)

The Responsive Images and SVG focus group, led by Anselm Hannemann, focused on img, picture, and their attributes, as well as a number of SVG elements and attributes. Read through their full results in the WPDS-HTMLSVG-Group spreadsheet. The group also took notes on quite a bunch of bugs and issues, to be found in this comment in the focus groups work document.

The JS API focus group was led by Francesco Iovine, who actually spent most of the day giving kick start intro sessions to newcomers to WebPlatform.org, enabling them to immediately start contributing. Along with on-boarding new contributors, the JavaScript API focus group added examples to the Web Storage API page. They also created and set up some missing API listing pages: Ambient Light API, Device Orientation API, Screen Orientation API, and Pointer Lock API.

Francesco Iovine giving kick start intros to novice users of WebPlatform.org

Francesco Iovine giving kick start intros to novice users of WebPlatform.org

The “Do what you want” group, led by Hans Christian Reinl, focussed on general web concepts, tutorials and beginners docs. Six pages got revised and updated, and two new pages were created. Four pages received updates and still have open ends, two others definitely need more work – find all details at the group work document.

The CSS focus group led by Christian “Schepp” Schaefer identified the following pages as being imported from MDN or MSDN, and reworked them according to the style guide: Selectors :last-child, ::before, ::first-letter, ::first-line; Functions translate(), translateX(), translateY(), translate3d(); Properties zoom, left, right, object-fit, transform, font-variant, text-shadow; as well as the syntax page for important!. The group also went through every single CSS property and removed all prefixed example code, just leaving the unprefixed CSS in there. Annoyingly they found a lot of CSS property pages that had an empty “CSS Object Model Property” table cell, or a wrong one, like “element.style.”. A few of those got corrected. Also, a dabblet bug was found on code.webplatform.org and fixed with the help of Renoir Boulanger.

Thanks to all the contributors and volunteers

This successful Doc Sprint would not have been possible without the help of our community experts and our lovely volunteers: Pascal Szewczyk, Tomas Caspers, Kenneth Shinabery, Daniel Connerth, Sven Wolfermann, Aaron Gustafson, David Kirstein, and my partner in crime in organizing the event, Marc Thiele. Thank you all.

Want to run a Doc Sprint yourself?

Doc Sprints like this one are a fantastic opportunity to help push the web and its documentation forward. In the same time and place, you can meet and exchange with like-minded folks, learn, get inspired, and also have a nice BBQ and party. So why not run your own Doc Sprint? We created a document for you in case you’d like to create the next #WPDS: the Doc-Sprint-in-a-Box.

A New Home Page

You may have noticed, we recently launched a new homepage for www.webplatform.org. The recently-retired homepage was doing its job, but looking at it more closely, we realized that wanted to provide users with much more information right from the first introduction.

a screenshot of the new web platform.org homepage

The new home page starts with telling the story of the project as directly as possible. What is this project? Who is involved? Why is this a great idea? What’s unique to this set of web documentation?

We made this page 100% responsive — it resizes to fit any size screen. And we moved the video so that you can play it right from this page, instead of having to click and wait for a lightbox to load before being able to watch.

The Docs List

We added a section listing the major sections of the Docs, showing which ones are ready to use, which ones are being worked on, and what ideas we have planned for the future. We hope this will make it easier for people to understand the state of the project, figure out where to jump in and help, and most of all, what documentation is already on the site, ready to use.

This list is a work in progress. The plan is to continuously update it with new links, and move links from column to column as the status of things change. People should be able to come to this list to quickly see exactly what’s on the site.

As I’ve gotten involved with Web Platform Docs, and dug into researching what’s going on, I’ve found that there’s a lot of great stuff going on that people just don’t know about. It’s my goal to make it much easier to find such treasures, and this section is a start.

a screenshot of the middle of the new homepage, highlighting the list of Docs

The lower part of the page is dedicated to explaining exactly how to get involved. Rather than asking people to read many pages in the Editor’s Guide, we wanted to put the most important information right up front where it’s easy to find and follow.

a screenshot of the bottom page of the homepage, with the information about how to contribute

I’ll be overhauling the Editor’s Guide, likely renaming it Contributor’s Guide next, to reflect what I’ve discovered about how to get involved, and to better match the message that’s now on the home page. Since Web Platform Docs is relying heavily on the contributions of volunteers to update and improve the documents that have been imported from MSDN, we need people to be able to join the effort with as little friction or confusion as possible.

A new platform

Lastly, we also changed the technology that’s driving this and other pages on the www.webplatform.org domain. Most of the Web Platform website is handled by MediaWiki hosted at docs.webplatform.org, while this blog is driven by WordPress at blog.webplatform.org. The home page, along with several other static HTML pages, are hosted separately at www.webplatform.org. These were hand-coded pages that used a bit of php includes to handle the header and footer.

We revisited this set-up when we were getting ready to launch the new home page design, and decided to implement a static site generator. While there are many (Jekyll perhaps being the most popular), the team wanted to use something built on Node.js, since Node.js is JavaScript and JavaScript is part of the web platform. Renoir Boulanger researched and tested quite a few node.js-based static site generators, and settled on DocPad. We wanted something that would create a file structure that would be easy for anyone to understand — that way the source files could be shared in a new public GitHub repo, where anyone could submit a pull request with changes. We want everyone involved with the Web Platform project to have an easy way to submit suggestions for updating the content on the homepage and other pages.

a screenshot of the new GitHub repo that hosts the static pages from www.webplatform.orgThis is just one more step in improving the Web Platform project. We will keep improving both the design and content of this homepage, bit by bit. Let us know if you have any suggestions or ideas for how to keep improving things.

Fluent Doc Sprint is next week

We have already blogged about the upcoming Doc Sprint at Fluent 2014, but I’ve compiled a few details, in case you have questions. You can also get a sense of what happens by reading about past doc sprints by checking out our previous posts.

First of all, the Fluent conference is hosting the Doc Sprint, providing the space & food. But you don’t have to go to the Fluent conference to attend the Doc Sprint. The Doc Sprint is open to the public. That means anyone can attend.

Yep, that means YOU are invited. So, what will happen when you come? The agenda will go something like this:

MORNING:

  • Welcome
  • Intro to WebPlatform.org docs
  • How to contribute
  • Doc Sprint!

LUNCH (yes, free food!):

  • Working, talking, sharing ideas

AFTERNOON:

  • Special guests Doug Schepers (W3C), Jen Simmons (Jen Simmons Design), and maybe a surprise or two…
  • More Doc Sprint!
  • Swag
  • Wrap-up

No experience is necessary. Seriously. That means you don’t have to be an expert, you need not know how to edit wiki-markup, or be familiar with any build tools. It’s a good idea to be there at the beginning, just so you get the information about getting started contributing. We’ll go over everything you need to know. Bear in mind that you can come for just part of the day, too.

We’ll be in Salon 5 at the San Francisco Marriott Marquis780 Mission Street, San Francisco, CA.

You will need your own laptop and power (and power adaptors).

For any other questions, go ahead and email the webplatform public list. And do sign up at Eventbrite to get the latest information and special treatment.

See you there!

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.

Gusty doc sprint at UW in Seattle

What do you get when you mix WebPlatform Docs, University of Washington, Western Washington University, W3C spec editors, web developers of all levels, a winter storm with gale-force winds, loss of power to 20,000 Seattleites, and a few bowling lanes? The second Seattle Doc Sprint, of course.

University of Washington entrance

This past Saturday, Microsoft hosted a doc sprint at the University of Washington. This was another successful mingling of WPD community members, coming together to beef up the content portfolio we maintain. We specifically reached out to students at UW and at Western Washington University (and bravo to those who made that two-hour trip, given the horrendous weather) to create a mix of people who are still learning and those who are actively practicing web development. All-in-all, about 45 people met in the Husky Union Building (the HUB). We kicked off the day with delicious Italian pastries and good strong coffee, and then got right to it. We had great energy in the room, and it showed in what we accomplished.

Doug Schepers’ talk, delivered from the East coast via Skype, kicked things off. Doug talked about the importance of the project, and more poignantly, why it was a good idea for everyone to give up their Saturday and venture out in the storm. After Doug’s talk, I gave some quick background about WebPlatform (you can see the slides on my share) and what we were working on. Then Alan Stearns spoke about what’s happening in CSS, how to edit a CSS property page, and where to get help for editing MediaWiki. Then, we were off to the races.

We had only a few goals for the sprint:

  • Review CSS property pages that have been marked as done
  • Review HTML element pages

But that was plenty! The low-hanging fruit were the pages that just plain looked good, and we found a lot of those. Others were missing a value or example. Some needed just a tad of editing. In reviewing the pages, some contributors felt more comfortable marking down in notes what needed further work, some ran into issues in creating content, but most just hit the edit button and just went for it.

Working at the doc sprint with various levels of success

The HTML elements were a little more uneven. Some of the pages have received a great deal of love and looked bellisimo! We gave some other pages a little extra TLC, in order to make them as beautiful as that first set. And there were times when working on some of the elements required working on some attribute pages as well, so we did that, too (thanks, apexskier!).

A big shout out to all who attended and took part in the doc sprint. This was a ridiculously hard working group of contributors. I practically had to beg everyone to break for lunch. When all was said and done, these hard-working souls reviewed, edited, created, and curated 201 topics by the end of the day, an astounding amount! We all were rewarded by the knowledge that we did a lot of good work. And everyone who participated was further rewarded with a WebPlatform t-shirt and John Allsopp’s book, “Developing with web standards.” And one fellow with abundant good fortune won a Microsoft Surface Pro.

Winner of the Surface Pro

We’re looking forward to more doc sprints both here in the Puget Sound region and around the world! And in case you were wondering, no, we did not lose power on campus.

Special thanks to Alan Stearns of Adobe and David Storey, our local CSS and WebPlatform gurus, who tirelessly roamed the room and answered questions about HTML, SQL blocks, CSS, what makes good pizza, and many other topics.

Post-doc sprint bowling in UW's HUB

Post-doc sprint bowling in UW’s HUB

Birthday-party-slash-Doc-Sprint, Amsterdam, October 12, 2013

Never doubt that a small group of thoughtful, committed citizens can change the world; indeed, it’s the only thing that ever has. - Margaret Mead

Also, never doubt that a small group can get a lot done at a doc sprint, and the group at the Amsterdam doc sprint, however small, accomplished a lot of work on Web Platform Docs, moved the web forward, and changed the world. A small group, however, does have trouble polishing off a huge, chocolatey birthday cake, and we really could have done with more attendance on that front.

Indeed, the cake was not only not a lie, it was delicious. Careful with the knife, Doug.

The cake, the catering, and the venue, The Hub co-working space, were all orchestrated by our host, Paul Verbeek. Paul also coordinated with the Fronteers organization, which helped publicize the doc sprint, as it followed the Fronteers 2013 developer conference. Everything came off with great panache! Thanks, Paul!

The big story coming out this doc sprint is that we finished some 53 CSS properties, to bring the total number of CSS properties completed to within twenty of our goal for the project. Some of the work on those 53 properties was already done, in other doc sprints and by other contributors, so we mostly reviewed and put the finishing touches on these properties, and we were able to move very quickly through the list.

There are opportunities for us to add value to the web, apart from great documentation. In documenting the new auto value of the outline-style property we discovered that the specification did not describe exactly how the auto value should work as a standard, the spec leaves it up to the user agent, and when we tested it in several browsers on several systems, we were unable to discern a common pattern. This struck us as falling short, so we dispatched a missive to the CSS working group, recommending that the behavior of the auto value be more clearly defined. We’re waiting to hear back from them. But the point is, we took the opportunity to not only document the auto value, but to help shape its specification and participate directly in building the web.

Some prefer to sprint in their socks.

Many of the participants here in Amsterdam have also attended one or both of the other European doc sprints. Rodney RehmVivienne van Velzen, and Francesco Iovine, veterans of the Berlin and Zurich doc sprints, made a mountain of edits to the CSS properties and HTML attributes documentation.

Is it time for cake yet?

We also signed up several new members, one of whom, Tom Schuller won the raffle prize, a Chromebook provided by Google.

Show up at a doc sprint, win free stuff!

The local luminaries also graced us with not only an appearance, they chipped in on the CSS properties and worked on developing automated compatibility information for WPD. Peter-Paul Koch of Quirksmode fame, Ronald Mansveld, and Niels Leenheer of HTML5Test are working with Doug Schepers of the W3C to aggregate compatibility information from across the web and display it on Web Platform Docs.

The Syndics revisited. This time, it’s the fabric of the web.

Okay, one last cheesy mashup featuring the work of Dutch masters of the Golden Age, just to tie up the analogy above, and hopefully put an end to all the silliness of the last three blog posts:

The real Syndics did show up, but left abruptly when we told them the Linen API wasn’t standards-track. [The Syndics of the Drapers' Guild, by Rembrandt Harmenszoon van Rijn, courtesy of the Rijksmuseum.]

So, even if we couldn’t finish the cake, we certainly took a big bite out of the work on Web Platform Docs. As this post goes to press, the CSS properties are being finished and the last loose ends of that project are getting tied up. We look forward to developing a new JavaScript reference and over-hauling our HTML elements and attributes in up-coming doc sprints. We hope you’ll join us!