Web Platform Wednesdays, Week 4: Visual formatting

For Week Four of Web Platform Wednesday, we focus on the visual formatting model properties: margins, padding, width, height, position, float, clear, display, top, right, bottom, left, z-index, direction, and unicode-bidi. Best practices are scattered all over the place for some of these basic properties:

Folks need explanations and examples that are tried and true, that use best practices, and that follow design principles, such as simplicity, visibility, and reuse. A lot of thought can go into crafting one of these CSS properties pages. Contributing to one of these properties is a great way to deepen your own understanding of the basics. What are the experts saying about using the property now? How are designers and developers creating new uses for new browsers, devices, and workflows?

But first and foremost, the Web Platform Wednesday project is focusing on the basics: ensure the syntax, descriptions, and examples are accurate. You don’t need to be an expert to look at a page and make sure the values match the spec, or that it provides basic facts or solid examples. That’s why we’re here: to get the facts down and to provide clear, usable information about these properties. Join us this week as we form the foundations of this dynamic resource.

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

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

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

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.