Web Platform Wednesdays #5: Examples!

It’s a busy week for a lot of students, and for us here at WebPlatform.org, so we’re taking it easy on ourselves this week and doing the fun stuff: example code!

For each CSS property we’ve done so far, we want to make sure we have a simple, clear, canonical example for all the possible value types. For example (no pun intended), font-size allows the author to specify the size several different ways: absolute-size, relative-size, length, or percentage.

What does all that mean? That’s where an example will really help out.
Continue reading

Web Platform Wednesdays, Week 3: Texting!

You shouldn’t text while driving, but you should text while designing, and CSS3 puts the power in your hands to text with style! This week’s Web Platform Wednesday focuses on the properties from two related CSS Level 3 specifications: the CSS Text Module and the CSS Text Decoration Module.

Some of these properties will need attention by experts familiar with Asian languages, but some of them are purely visual… and hot! Help us complete these properties, and get the CSS Firestarter badge, available only to those who contribute to Web Platform Wednesdays.

The topics this week are a variety of text properties: text-wrapping, white-space, justification and alignment, spacing, edge, decoration, emphasis, and shadow. Does one of these interest you? Then take on one of these simple tasks for that article:

  • Basic facts, such as overview table, syntax, and values
  • Explanatory text, such as the introduction (summary), usage, and notes
  • Examples, with explanations
  • Links to tutorials and other materials (either inside WPD or on the wider web), to the relevant specifications, and cross-linking keywords to other reference articles
  • Review, including flagging and unflagging

To get started, let one of the coordinators know on our public-webplatform@w3.org email list, or ask for direction on our Freenode #webplatform IRC channel, or even our @webplatform Twitter account. A coordinator will help you get you started.

Our first two weeks were very successful, tackling almost 50 properties! At this rate, with help from you, we will have comprehensive reference articles for all CSS properties in less than 3 months!

Web Platform Wednesdays

Documenting the web, even just client-side technologies, is an enormous undertaking. We can’t do it alone, and we can’t do it all at once.

We want to send a clear signal to the web developer community about where our site is the most useful today, where it’s going next, and when it will get there. And to those who want to contribute, we want to make it clear and easy how to help. We also want to make sure that the content contributions are high quality.

To meet these goals, we’ve decided to focus on one main topic area at a time, break it down into manageable morsels that can be accomplished in a week, and systematically craft each article one at a time.

CSS properties are an area of rapid growth and great developer and designer interest, and with the recent integration of our CSS property reference documentation into Brackets and other upcoming projects, CSS properties seemed like a good place to start.

Though we have been working on the CSS properties here and there, at doc sprints, and whenever a few of us have the time, we aren’t moving fast enough. We need a coordinated effort, one that involves the larger community, and one which makes use of an on-going operating mechanism.

So, each Wednesday, we will announce a new set of CSS property articles that need work, and ask for volunteers to pick a task for one or more articles, work with the coordinator for that article, and report back when it’s ready for review. This way, we can systematically reach our goal of CSS property excellence by the end of July.

This first week, we are concentrating on outline properties, and border properties for color, style, width, and shorthands.

Welcome to Web Platform Wednesday!

Continue reading

New JavaScript Docs from MSDN!

Let’s face it, a site for Web documentation that doesn’t have solid JavaScript docs is like a browser that doesn’t have JavaScript. Up to now, the JavaScript topic on Web Platform Docs has been sparsely populated, especially our reference articles. That’s why we were so thrilled when Microsoft offered us their excellent JavaScript documentation from MSDN.

These 400+ articles will give Web Platform Docs a foundation to build up a robust library describing the use of JavaScript in modern web development. The donation is substantial, but it leaves room for a expansion and enhancement from our community. But the first step is integrating these articles into WPD.

So, this is where you come in!

Continue reading

Credit Where Credit is Due: Content Attribution and Community

One of Web Platform Docs’ core tenets is attribution. Attribution is as central to our mission as our founding principles, the three pillars of Pragmatism, Inclusion, and Consensus.

So, just what is attribution? In our case, it is keeping track of who has contributed what, and sharing that information with our users. Web Platform Docs tracks attribution in two key ways: for content submissions by individuals, we log every edit by user name; for content contributed in bulk by organizations, or transferred over from another project like MDN or MSDN, we explicitly note the original source.

As an open collaborative project, attribution is critical from a legal, practical, and motivational perspective.

On the legal side, our license is CC-BY, or Creative Commons Attribution. When users agree to the site license, we all agree to honor this. Failing to provide attribution, or removing past attribution, is a violation of the letter and spirit of this license. Note that there are a couple of exceptions to this.

On the practical side, attribution is used for fame and blame. Fame is praising the original contributor for their content, so people know who to credit and thank when they are reading, learning from, or reusing the content; it also helps us to think about who to ask to do future work. Blame is the flip-side of the same coin… it helps users (and reusers) to evaluate any possible bias on the part of the original contributor, as well as identifying contributors who need guidance (and spammers). Provenance is a powerful and versatile tool.

On the motivational side, we are lucky enough to have many primary bulk content contributors (such as Google, Microsoft, Mozilla, and Opera), and we hope to have large numbers of community contributors over time. In addition to altruism, part of what motivates these contributors is that well-deserved fame. Remove that attribution, and you undermine motivation, and the project suffers. Even people who don’t want notoriety per se still have a sense of fairness, and may be discouraged if their contributions are not afforded equal treatment; potential contributors may be either encouraged or discouraged by seeing how contributions and attributions are handled.

For existing resources, of course, attribution itself is not enough; they must be willing to contribute their content to Web Platform Docs. Where the source material isn’t already available under a compatible license, we need  to seek an agreement with the owners to reuse it under our license. Even where licenses are compatible, such as on a site that uses CC-BY, we want to ask that source to use their material first, so we maintain our reputation as a good citizen of the web documentation ecosystem.

So, we encourage all of our contributors to always get permission and give credit when adding content, and only to remove existing attribution after community discussion. And we invite our users to feel free to reuse our content with confidence, knowing just where the material came from. For more detail, you can read our guidelines on external attribution.

Register Now for W3Conf and Web Platform Doc Sprint, 21-23 February in San Francisco

In just a month W3C and Adobe are teaming up with other partners to host a developer conference and a Web Platform Doc Sprint.

W3Conf, W3C’s conference for developers and designers, is coming up on February 21-22 at the Regency Ballroom in San Francisco. This is not just another conference on web development, but a showcase on the most pragmatic aspects of web standards, stuff you can use today. The opening session, delivered by Mozilla’s Janet Swisher and W3C’s Doug Schepers, will feature Web Platform Docs and community involvement. Other speakers who have contributed to WebPlatform.org include CJ Gammon on digital books, Lea Verou on CSS secrets, and Alexis Deveria on cutting-edge web features, along with many other great presentations. See the full list of speakers and talks on the W3Conf site. The closing keynote on CSS layout is by Eric Meyer, and a twist on the classic browser panel will give voice to an authoring tool vendor and a developer and designer from the audience (maybe you!) to represent the view from the trenches.

The accompanying Doc Sprint to bolster the content on Web Platform Docs will be held the day after the conference, Saturday February 23rd, at the Adobe office. This is a free all-day event where you can meet the developers behind WebPlatform.org, and learn how you can help create content on Web Platform Docs, or even take the lead in areas that you’re an expert on. Contributing to Web Platform Docs is a great way to let your light shine.

Come join us for both events! Register for W3Conf with the promo code webplatform and get $120 off the fee. And don’t forget to register for the Doc Sprint… it’s free, and a great way to get involved.

Intel Joins Web Platform Stewards

We are overwhelmed by all the interest and active participation Web Platform Docs has garnered so far. We’ve had many organizations ask about becoming a steward in order to help make sure the site lives up to its potential.

We’re pleased to announce today that Intel is the first company to sign on as a new steward since the initial alpha announcement.

Intel has demonstrated their long-standing commitment to standards, open source software projects, and education, and has been a W3C member for many years. We are excited that they are extending their commitment as a Web Platform Docs steward.

People who use Web Platform Docs want to know how to build web apps that perform well across devices and architectures. Intel brings to the table a lot of experience with different systems, and has indicated their plans to contribute to our documentation.

As we continue to improve the site, refine our infrastructure and build up content in preparation for our formal launch, we anticipate many more stewards will sign on, and we are grateful that Intel is the first of these. We actively invite other organizations to consider joining Intel, along with Adobe, Apple, Facebook, Google, HP, Microsoft, Mozilla, Nokia, and Opera, as a steward of WebPlatform.org. You can find out more on our stewards page.

Welcome, Intel, and thank you for your support!

Update: Intel has announced their own developer site, the Intel® HTML5 Zone. Over the coming months, we will work with Intel to pool our resources to best effect for Web Platform Docs, and for Web developers. We are very excited about this relationship. You can read more on the Intel news bulletin.


Spreading the News

Since we launched on Monday, we’ve seen a number of different ways people are getting the message out about WPD: blogs, news articles, tweets, press releases, and more. Alex Komoroske, Peter Lubbers, and Scott Rowe—all with Google—have put together a 30 minute video that’s a tour of our effort. This includes an overview of the site, a history of the content, instructions about getting started, possible future features, answers to viewers’ questions and much more. Take a look:

Have you used any unusual methods of telling friends and colleagues about WPD? Keep it legal, and keep it friendly, and let us know what weird ways you’re delivering the news about our site.

One Small Step

Welcome to WebPlatform.org.

This site is really just the starting point for great things to come.  The goal of this site is to be the place to come for answers to your trickiest (and simplest) development and design questions about the Open Web Platform.

For years, web developers have had to rely on multiple sites to help them learn web programming or design, each with one piece of the puzzle. Great sites appear, covering one or two subjects, but too often fail to keep up with the rapid pace of changes to the web platform. This may have been good enough when the web was just simple HTML, basic CSS, and maybe a little JavaScript, but that was a long time ago. Today’s web is more than just documents, it’s applications and multimedia, and it’s changing at a breakneck pace.

WebPlatform.org will have accurate, up-to-date, comprehensive references and tutorials for every part of client-side development and design, with quirks and bugs revealed and explained. It will have in-depth indicators of browser support and interoperability, with links to tests for specific features. It will feature discussions and script libraries for cutting-edge features at various states of implementation or standardization, with the opportunity to give feedback into the process before the features are locked down. It will have features to let you experiment with and share code snippets, examples, and solutions. It will have an API to access the structured information for easy reuse. It will have resources for teachers to help them train their students with critical skills. It will have information you just can’t get anywhere else, and it will have it all in one place.

But it doesn’t. Not yet. Right now, it has a wiki, docs.webplatform.org, which anyone with an account can edit, and structured templates for ensuring consistency. It has a massive import of data from Microsoft, Opera, Google, Facebook, Mozilla, Nokia, Adobe, and W3C, still in a rough form, that needs a lot of polishing. It has a chat channel and Q&A forums, and a blog. And all this material will be available free, for anyone to use for any purpose.

This is an alpha release. There is much to do, and we think that the best way to achieve our goal of a comprehensive, up-to-date, and useful site is to enable the entire community to shape it, to meet our needs together. So in the spirit of “release early, release often”, we decided to announce the site at the earliest possible point, and improve it in public… with the web community.

This site has the backing of some of the biggest players on the Web: Adobe, Apple, Facebook, Google, HP, Microsoft, Mozilla, Nokia, and Opera. These organizations are stewards for the project, enabling W3C to convene the community and grow the site. Beyond their strong organizational commitment, dedicated individuals from these organizations have invested time to make this happen. Moving forward, it will likewise be dedicated individuals –hopefully including you– who help keep the site up to date, make sure that the information is pragmatic and useful, that the features meet real-world needs, and that people find the help they are looking for.

The stewards, those organizations who have put so much into this so far, are going to keep putting people, content, money, and effort into the site. But they are doing so as peers, with the same privileges available to anyone else who builds up trust and becomes a site admin.

Over the next few months, we will be asking extraordinary members of the community to help lead teams that will tackle particular challenges, whether that is creating new content to strengthen a particular topic, or helping translate the site into their local language, or patrolling the site for outdated, erroneous, or biased content.

Web Platform Docs is the first, and most important piece, of WebPlatform.org. We are here to help you, and to ask for your help to take this giant leap forward for the Web.