Web Platform Wednesdays, Week 3: Texting!

by
0 comments

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: Week 2!

by
0 comments

Last week’s Web Platform Wednesday was a rousing success! Our community looked at all of the target property pages, and you reviewed and completed most of the ones we lined up. So this week, we start in on Wednesday May 15th, 9am (PST). It’s time for round 2: DING! DING!

Not only do we hope to finish reviewing any pages left from last week’s target CSS property pages, but we will also work on four new groups of pages:

Please hop on board and pitch in. Even a small contribution to a single page is much appreciated. And it’s pretty straightforward. You can edit any or all of these for each 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, send a quick note declaring your interest on our public-webplatform@w3.org email list, or ask for direction on our Freenode #webplatform IRC channel, or even our @webplatform Twitter account. Someone will help you get you started.

Each article has a coordinator managing it. Check in with them (just to make sure there’s no duplication of effort), and dig in. We provide the link to the target article and to the definition of the property in the appropriate CSS spec. Most tasks will be self-explanatory, but if you need help or guidance, the coordinator is there for you.

Doug’s post from last week summed up really nicely what this is all about, so please give that a read if you want some more information about how this got started.

Web Platform Wednesdays

by
0 comments

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 →

Web Platform Docs API used in Brackets

by
2 comments

A basic goal of WebPlatform.org is to be the site where you can come for answers to your trickiest (and simplest) development and design questions about the Open Web Platform. Along with being a site, we also want to be a service — or really to be of service, as the saying goes. Besides being a central location where you can get information, we want the information to get to you. So we’ve provided APIs for retrieving the content in-context.

You’ve seen it before in editors. You select “Help” and documentation pertaining to the code you’re typing shows up in your editing window. It’s referred to on Wikipedia as “Context-sensitive help“. And it’s great, because, right as you’re coding, you can check a method signature, or get an explanation or a sample. The key is the content: Is the feature proprietary? Widely adopted? Is the help current? If Web Platform Docs are being pulled in, you know where you stand: it’s documenting the open web. And you’re getting the latest content we have.

Being on the MediaWiki platform means that we can provide an interface for structured information reuse. You can try it now. In your browser address bar, just type:

http://docs.webplatform.org/w/api.php?action=parse&page=css/properties/box-shadow

OK, it’s not pretty, but you get the idea — or actually, the xml result. Adding a format parameter &format=json gives you the results back as a JSON object. You can read more about the default calls in the MediaWiki developer documentation.

So, the API was lying fallow, when Adobe’s Alan Greenblatt (@agreenblatt) decided he wanted to contribute something useful to the Brackets project. If you aren’t already using Brackets, you should check it out: it’s an “open-source code editor built with the web forthe web,” which is a great match for what we’re doing at WPD. WebPlatform.org individual contributor, David Kirstein (aka: frozenice) worked with Alan to explore and adjust the API. The result is in the latest release of Brackets. With a simple Command/Control K, the reference content for a CSS property appears in the context of your CSS code!

As it stands, it’s a pretty neat little API, but there are considerations when using services. Mindful plugin models should be employed when implementing a documentation-as-a-service. For example, we’re still working on our infrastructure, and so there was a concern about having a lot of individuals hitting the site. Also, the Brackets team wanted to take some basic security measures. So, for this early implementation, he decided to preprocess and package the results.

The Brackets implementation includes a “Read more” button, which sends the user to the full page in the browser. And that’s where the details lie: Right now, we’re working on getting key content up to beta quality. So that button should say: “Read more, and if you think you know better, please don’t hesitate to edit the page, and make it better.” Because after all, WebPlatform Docs is “Your web, documented.” For more information on registering for the site, talking with the community, and contributing, select Editing from the top menu on any page.

That’s the scenario: You’re in the throes of a project; you need a reminder or an explanation or some sample code; you get WebPlatform.org content within your working context; and if you can, you leave that page a little bit better for the next developer.

New JavaScript Docs from MSDN!

by
0 comments

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 →

Doc Sprint San Francisco, April 3

by
0 comments

The Google offices in San Francisco are nestled in a cluster of buildings the erstwhile center of the caffeine universe and the headquarters of Hills Bros. Coffee. It was here, where beans were once unloaded from ships, roasted, ground, canned, and shipped to supermarkets all over the U.S., that we attempted to apply the same level of industry to the production of more modern commodities: Web Platform Docs.

Eschewing the brown water of days gone by, we embarked with (good) coffee and breakfast in the Google cafe, which was right next to our designated conference room.

The Doc Sprint was a lot of fun…and rewarding, too! I probably gained at least five pounds, though, with all the great food. -Dan Stormont

Peter Lubbers had expertly made all the arrangements and had all of the name tags ready for participants, so getting in, grabbing a bite, and getting to work were unhindered.

. . .

Julee Burdekin spent the day helping contributors on the CSS Properties project: Macy Wong, Carlos Araya, Heather White, Emuvente, Angela Lau, Dan Stormont, and Doug May touched 47 properties, including reviewing existing properties, adding samples, and working on new properties. The status of 32 properties was updated, including 6 moving into review, and 16 reviewed. Great work!

Other outstanding contributions:  Richard Trott cranked out more small-but-indispensable edits than should be humanly possible; Tony Sukiennik, explained the WebVTT format in the audio-video API ; Jack Chi, cooked up a nice XHR example; Romain Briand translated our main page to French; Pius Uzamere pushed a lot of bits for HTML span and other elements; Linda Sager improved the Web Typography and other conceptual articles. Folks found lots to do on the site, and they chipped in some great content!

. . .

Ryan Lane, our man at MediaWiki worked on the Evil Session Bug, made an initial site map of WPD, published the skin in Wikimedia’s Gerrit, and got an initial development environment set up in Wikimedia Labs to run experiments. [Late breaking update: I dare say, it looks like Ryan fixed the infamous Evil Session Bug!!!]

After a delicious lunch (again in the Google cafe, gourmet all the way, etc.), Michael Mullaney, CEO of Sencha delivered a rousing presentation on SVG filters. (Doug Schepers is kicking himself for not being there as you read this.) Michael’s presentation followed the detailed article he contributed on the SVG feColorMatrix element with several image and code examples. People use the word, “awesome” too much, yes. But Michael’s contribution to WPD and the wider community is dictionary-definition awesome.

. . .

More celebrities: Christian Heilmann came by to chat with us as we drank (Californian) beer and munched on finger foods in the Google cafe over-looking the Bay bridge. Always fun to hang out with Chris!

I am glad I participated in the Doc Sprint. It feels great to make a contribution and learn in the process! Now I’m hooked. :) -Angela Lau

We raffled off a ChromeBook, and Carlos Araya took home the prize. Congratulations, Carlos!

. . .

Thanks to everyone who came to this event! In all we had 43 participants at the local doc sprint and several who were there in spirit via TCP/IP. Our stats are incomplete because I was only able to gather three hours of data – and if I missed your contributions in the items above, please accept my apologies.

Having great fun doing this and it’s a nice feeling to contribute and being part of this exciting and important endeavor. Great lunch at Google SF campus is a cherry on top! Thanks, Google for hosting. -Linda Sager

Also, we especially thank the 20 participants who contributed their responses to our survey. These results are encouraging in that they show some improvement in this doc sprint over previous sprints, and they offer many pointers to where we can continue to up our game. Keep the feedback coming!

. . .

So on this, the birthday of Herb Caen, champion of three-dot journalism and old-school canned brown water (that’s right, Frisbeetarian that I am, I just couldn’t resist a paean to Caen; for those of you who didn’t grow up in San Francisco, that’s why the elipses between paragraphs appear above), we humbly submit for the times yet another collaboration of Web Platform Docs, and dedicate it to Herb.

 

How we’re working, at WebPlatform.org

by
3 comments

I thought I’d share some thoughts this week on how we are working towards making web standards documentation rock more here at WebPlatform.org! We knew it would be challenging to deal with this much content, especially as we are mostly volunteers with only a finite amount of time available to work on the project. We’ve already achieved much, working towards our goal of making WebPlatform.org the definitive client-side web technology documentation site, but there is still much more to do. This is why we opened it up to the wider community as an alpha.

The plan has always been to include the public as early as possible. The web does, after all, belong to all of us. To facilitate getting things done, we have a number of communication means at our disposal. We have a number of discussion methods available including IRC and a mailing list. These are mostly used for general communication, such as announcing in-person Doc Sprints, soliciting feedback and discussing current and future work. For focusing on particular tasks, we:

  • Identify specific tasks to work on. To make the work more manageable, we have started to split it into manageable chunks and we work on each item in turn.
  • Discuss these tasks via our regular communication means, and also have more involved discussions at our regular weekly meetings, simultaneously held on teleconference and IRC.
  • Record task priority lists and who is working on each task, at our beta requirements page.
  • Create detailed task plans to outline how the work will be done, with subtasks, and people assigned to complete them.
  • Get on with the tasks!
  • Speed up task progress with intensive bursts of work at Doc Sprint events.

Current priorities

At the moment, the main topics we are focusing on are CSS properties and JavaScript APIs. Our plan is to perfect the topic pages for these two major areas over the next two to three months. This is where you come in! If you are knowledgeable and passionate about these areas, please get in touch with us to find out how best to contribute. If you don’t wish to contribute to either of these focus areas, and wish to work on something else instead, get in touch anyway, as we will be able to find something for you to do.

The next Doc Sprint we have coming up is in Berlin, Germany, this week — we expect to make a lot of progress on our priority tasks there!

Documenting the Future: CSS Regions

by
0 comments

Web Platform Docs is an ambitious project. It is challenging enough to document all the features that work across browsers today, without delving into experimental features. But it’s also critical for web developers to learn what’s coming up next. Such features are not as widely documented elsewhere, and getting early feedback on them helps make sure they are done right.

So when an important CSS layout feature like CSS Regions gets experimental support from two major browser engines, WebKit (Chrome and Safari) and Trident (Internet Explorer), we felt it was important to document it on Web Platform Docs. (You will have to enable experimental features to see how CSS Regions works.) CSS Regions helps solve a long-standing fundamental design problem: allowing content to flow smoothly from one layout element to another without forcing a position. With CSS Regions, you can create complex magazine-style designs in which content flows through freely positioned layout elements.

Mike Sierra wrote up a tutorial that shows how flows work, how to arrange a layout, enable it, control region breaks, style fragments, trim content, and create adaptive layouts with media queries. The new API starts with the css-regions package, and includes APIs, such as CSSRegionStyleRule, NamedFlow, and Region. New CSS property pages have also been added, such as flow-from, flow-into, region-fragment, and the @region rule.

Mike also posted an example he describes here:

http://letmespellitoutforyou.com/samples/region_mq_sample.html

Resize the window to see the simplified mobile layout the tutorial describes.

Credit Where Credit is Due: Content Attribution and Community

by
0 comments

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.