Documenting the Future: CSS Regions

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:

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

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 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, 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.

The 1st European Doc Sprint is Feb 8+9 in Berlin!

People all over the web are contributing great ideas and tools, and the momentum for viable, open, global web standards is growing every day. Unfortunately disparate, inconsistent, and outdated information still needs to be collected and perfected in one place we all can rely on. is an idea that is coming into being through corporate sponsors, open web stewards, and — most importantly — individuals who are taking charge and creating a workspace for quality documentation. Everyday people volunteer their ideas and their time and build great content in a single place. But we still have a lot to do.

Logo of Web Platform Doc Sprint

One way we get folks inspired is through our Doc Sprints. These concentrated days of documentation work allow people to get started, really get stuck in, and make rapid progress. They also provide direct face-to-face contact between community members who previously only chatted online. Doc Sprints are places with lots of great ideas flying around. Bugs get addressed on the spot. Mini projects spring up and get prototyped and utilized right away. But mostly, it’s a time to gather together individuals who care about the web to work towards common goals.

So without further ado … it is a privilege to announce that the very first European Doc Sprint is taking place, in Berlin, on February 8-9, hosted by Adobe.

The main focus will be on improving content, but in addition we also want to put weight on encouraging web community managers to run their own Doc Sprints. If you are a web community manager and would like to organize a Web Platform Doc Sprint of your own, we would love you to join us in Berlin so we can give you the information you need to get started! Make sure you select the appropriate ticket category on registration so we can have your special Doc Sprint Starter Kit prepared for you.

Join us in Berlin. And if you can’t be there in person, please join us on the Freenode IRC channel #webplatform. We are looking forward to seeing you at the first ever European Doc Sprint!

Agenda, more information and registration: