A New Home Page

0 comments

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!

A Great First Year!

Forty-thousand some odd page edits on 8,740 total pages by 23,939 registered users summarizes a year of effort toward creating the web’s definitive source for technical documentation. Web Platform Docs, is still just a baby, yet to emerge from pre-alpha into beta release, and there’s a lot of work to do before we can lend it the car keys, but it’s off to a great start!

Birthday

The community, armed to the teeth, heads out to document the web.*

Content, and lots of it

At this time last year we launched the site with a huge pile of content donated by Microsoft, Mozilla, Opera, the W3C, and Google. It had to be huge, and, consequently, it needed a lot of work. Updating and organizing the content was and is the most important activity on the site.

Thanks to the invaluable efforts of Dave Gash, Mike Sierra, Lance Leonard, and many others, we reorganized the API Reference, updating 9 imported API documents and adding 13 new documents, in over 730 pages. This provides the web with an excellent reference for many of the main HTML5 APIs, including a few that are documented nowhere else, like the WebAudio API.

We’ve also developed a comprehensive CSS properties reference. This reference is almost (over 275 properties) finished – well, almost finished enough to let Adobe Brackets and Chrome DevTools cross-reference the content so that it is available to users right in those tools. Too many of you to name here have contributed to this effort, but this project would be nowhere without the unflagging leadership of Julee Burdekin, and she would like to thank you all – you know who you are – for helping out on this. Keep up the good work, we’re almost done!

While the API reference and the CSS properties were the big content areas we could hold up and point to for this retrospective, there was a lot of work on the content generally, especially early on, just after it was imported. We quickly realized that we needed structures in which to organize all of the pages and landing pages for each area. Chris Mills did a lot of work on these, and Seb Desbenoit created the icons that neatly describe each of the content areas.

It is the world-wide web, and we’ve had a lot of help from some great translators like Nestor Rojas, with renditions of WPD pages in Spanish, Crotel who has provided many Chinese translations, and Hooney who translated several pages to Korean.

Infrastructure, to enable us

The daunting the task of wrangling the content was made less so when the community rallied to build better tools and processes to support WPD.

Jonathan Garbee, wiz-kid extraordinaire developed project.webplatform.org, our beloved issue tracking system. This was a huge improvement over the old Bugzilla implementation we started with, and it made building the site way, way easier.

One day in April, Search was suddenly working. We had launched with the Search functionality largely undeveloped. Denis Ah-Kang came to the rescue, fixed our Search, and thereby saved the community fistfuls of hair.

Enhancements to the templates and forms that deliver and present the content were needed across the wiki. A special shout out to Frozenice, Alex Komoroske, and the Template Corps for expertly developing the guts of Semantic Media Wiki forms and templates.

This site is all about code. We badly needed a way for users to play with code in real-time, and Lea Verou built the codelet tool, code.webplatform.org just in time for us to use with the CSS properties documentation.

Down in the engine room, we’ve benefitted from the expertise of Ryan Lane, who fixed the pernicious Session Timeout Bug, among many other invaluable contributions, and Renoir Boulanger, who, since he joined us as a full-time Operations Engineer, has been making enormous improvements in site performance.

Also, Renoir and Patrick D’Souza have been busy developing the analytics infrastructure to keep track of all this, and recently deployed Piwik, an open-source analytics engine.

Community, for the win!

Web Platform Docs is community-driven as well as a community destination. We also engage with the community through e-mail, the IRC channel, and blog posts (shameless plug). But when we need to do some heavy-lifting, we hold a Web Platform Doc Sprint.

These little get-togethers have proven to be the highlights of the year, helping build content, the site, and the community in a fun, productive forum. We’ve held eight Doc Sprints this year, both in the U.S. and in Europe. Peter Lubbers of Google, has administered Doc Sprints in San Francisco and Mountain View; Julee Burdekin of Adobe ran two Doc Sprints in San Francisco, Andre Jay Meissner of Adobe put on the Berlin and Zurich Doc Sprints, Eliot Graff of Microsoft ran the Seattle Doc Sprint, and Paul Verbeek did the Amsterdam Doc Sprint. These Doc Sprints are hard work, yes, but so worth it!

So, what’s next?

We have a birthday party to tell you about: next blog post (coming soon!). But if you’re still with me here you might want to know what we plan for next year.

Beta release – We expect to have completed the requirements for our first official release. Many of the items on this list are complete already (and celebrated above).

JavaScript – Microsoft has donated another big batch of content, a JavaScript reference, and Max Polk and Eliot Graff are getting ready to import it into WPD. We can’t wait to get started with updates and examples for this content.

DOM/Elements/Attributes – We need to develop an architecture that allows users to work with HTML elements, their attributes, and their DOM interfaces in a cogent, complete model. This will require new templates and forms as well as a thorough overhaul of the content.

There is a lot to do, and with any luck, we’ll NEVER be done. But if this last year demonstrates anything, it is that we can do it. Together, we have accomplished something important and valuable for the community. Thanks to all of you who have contributed to Web Platform Docs, and happy birthday!

* Image, The Night Watch or The Militia Company of Captain Frans Banning Cocq by Rembrandt Harmenszoon van Rijn courtesy of the Rijksmuseum.