SCOTT ROWE: CSS properties are some of the most ubiquitous
artifacts in web development.
You can't really develop anything for the web without
editing its CSS properties.
There are some 500 CSS properties, though the most
commonly used of these narrow down to a few hundred.
And it is these most commonly used properties that we aim to
document for the beta release of Web Platform Docs.
And we're excited to have third parties like Adobe
Brackets and Chrome Dev Tools using this information in
their products.
This video serves to supplement the information
you'll find on the CSS property project pages.
In other words, yes, you'll still need to read the Web
Platform Wednesday Doc and the CSS Property Editing Guide to
be prepared to contribute to this project.
Once you're ready to start, visit the Web Platform
Wednesday page to choose some properties and
tasks to work on.
Every Wednesday at 11 o'clock AM Pacific time, seven o'clock
PM UTC, we gather on the free node IRC channel #webplatform
to go over the list of properties
designated for the week.
You can either post to the channel with the properties
and tasks you want to work on, or you can send an email to
public-webplatform @w3.org.
You'll be contacted by a coordinator who will help you
work on the project.
But you don't have to wait until
Wednesday to get involved.
Send an email any time.
Wherever possible, choose a group of related properties,
so you can take advantage of any cut and paste shortcuts.
For example, Rob Simpson has signed up to work on several
text decoration properties.
He sent an email to public-webplatform@w3.org, and
coordinator Julie edited the table to sign him up.
You won't need to edit this table.
Just stay in contact with the coordinator as you work, and
the coordinator will update all the record keeping.
Often you'll have a group of related properties that
includes a shorthand property.
Think of the shorthand property as the master
property of the group.
For example, the text decoration property is the
shorthand property for the text decoration color, text
decoration line, and text decoration style CSS
properties.
Once the coordinator has signed you up for the
property, click on the link in the table and open the
Properties page.
If the link is red or the page does not exist, contact the
coordinator.
If your group of articles includes a shorthand property,
work on the page for the shorthand property first.
You'll need to refer to the w3 specifications.
Pull up the specs cited in the fourth column of the table,
then search the page for the property you were working on.
Ah, they moved it to a different spec.
This sort of thing happens a lot with specs.
They're constantly changing.
Also be sure you're referring to the most up to date spec.
At the top of the specification page, there are
listed all of the pertinent versions.
Use the latest editor's draft spec.
In page search is your best friend.
Notice that the shorthand property is described after
its component properties.
This is typical.
Note also that the specs contain a lot of superfluous
information.
This is because they are intended primarily for browser
developers who are implementing the standard, not
necessarily for application developers and designers using
the standard.
Your job is to distill from all of this information just
what a developer or designer needs to use the property in
an application.
We'll go over how to include this information in your dock
a little bit later in the video.
However, not all the information about the property
may be found in the spec.
Review other documentation sources for more information
and to get familiar with the property.
As you find information in other sources, be careful to
use it only in a manner that does not violate any
copyrights or license restrictions.
Don't plagiarize.
In Web Platform Docs, we always provide content
attribution when information is drawn
from external sources.
See the Editor's Guide for more information about license
and copyright issues and external attribution.
We'll go over external attribution in greater detail
later in this video.
While CSS properties are the focus of Web Platform
Wednesdays, you can sign up to work on specific tasks for CSS
property pages, or you can sign up for all tasks on a
given page.
The tasks are documenting basic facts, explanatory text,
creating examples, links, and reviewing complete articles.
The basic facts include the values in the overview table,
the syntax, and the property values.
You can copy and paste these values and descriptions from
the specs as they are.
The spec says for the animatable value, see
individual properties.
Usually if all of the longhand properties are animatable, the
associated shorthand property is animatable too.
You should always test it.
Ask the coordinator if you need help testing properties
for animation.
For the CSS object model property, this is usually the
same name as the property with the hyphens removed and the
words combined with camelCase, as shown here.
By the way, you can ignore the percentages field.
Notice that the border style value none has a link to more
information about background image here in the W3C spec.
Be sure to pull all that information into your
documentation.
In this example, that the image layer counts, but is not
drawn when the value is none, and include a link to the
related WPD page, in this example, the background image
CSS property page.
In other words, be sure to include all relevant
supplementary information in the value descriptions.
Notice also that we use code formatting to style the text
for other property values described.
In the hidden property value description, the words none
and hidden are formatted as code to set them off from
ordinary text.
Once you have all the values documented, the syntax section
displays them as code syntax automatically.
The explanatory text in the summary, usage, and note
sections is where you will contribute to
your original content.
You will contribute your original content gleaned from
your research in the specs and related documentation.
Here, it is really important that you contribute only
original content.
No cutting and pasting verbatim from other sources.
The article summary should briefly describe the property.
If the property is a shorthand property, the summary should
say so and link to all of the properties associated with the
shorthand property.
The usage section provides guidelines for using the
property and any little gotchas not obvious in the
descriptions.
Notes describe considerations for how the property works,
usually beyond the user's control.
Don't worry about the important notes section.
This is just an artifact from the initial content import.
Now for the funnest part, the examples.
Keep these super simple.
Save the complex, fancy examples for a tutorial
another day.
Your example should demonstrate
this property only.
Don't introduce other properties or make the example
dependent upon the knowledge of other properties.
Also, the example should be self explanatory.
To create an example, start with a new codelet at
code.webplatform.org.
First, I save as new to create a new codelet.
This will assign a file name to the codelet.
Then I replace the dummy content with my own.
You should test your example in all of the major browsers.
Watch out for deviations from the spec
when you run the example.
It turns out that dotted lines in Chrome are composed of
square dots instead of round ones, as they are in Firefox.
I'll go back and adjust the description accordingly.
We want to catch and document these little deviances and
details wherever we find them.
In this example, I've set up an element to
demonstrate each value.
However, you can also set up your examples to be more
interactive.
In this example, the values for the property are provided
in the comments, so a user can just plug
them in and play around.
But that's about as complicated as you should make
your example.
Don't get carried away with creating drop-down menus for
all the values, or otherwise building a playground up here.
That will only clutter the code and distract the user.
Once you have a nice working example, copy the pertinent
code back into the page for the property you
were working on.
Notice I'm only including the CSS code, not the HTML, here
in the CSS property documentation.
Also, copy the URL from the codelet example to the live
example URL field, which will be the value for the View Live
Example link in the published doc.
To create a link to the W3C specification, under related
specifications, copy and paste the title of the specification
into the name field, the URL for the spec into the URL
field, and the status level into the status field.
Some properties belong to more than one specification, so be
sure to include references to each specification.
You can skip the compatibility sections.
We're replacing these with automated data.
In the see also section, skip topic clusters.
These two are getting an overhaul.
In the manual links field, include cross references to
related CSS properties and other internal resources, such
as tutorials from the CSS tutorials page.
In the external links field, include any references to
relevant external content.
In the topic section, check the box for CSS.
Don't check any other boxes.
In the external attribution section, leave any checked
boxes the way they are.
And if any of the content you contributed came from an
external source, check the box for that source and include
the link to the source in the link field.
That's it for the edits for now.
Remember, you can always come back later and edit some more
in case you remember something you've forgotten.
If you are not the reviewer, be sure the needs review check
box in the high level issue section is checked.
If you are the reviewer, make any corrections or additions
to the content as needed.
Once your review is complete, uncheck the needs
review check box.
If any other high level issues check boxes are checked,
please resolve the issue and uncheck the box or note the
issue for your report back to the coordinator for Web
Platform Wednesdays.
When you're all done editing a page, under edit details,
enter a summary of the work you've performed
and click save page.
If you're working on CSS properties as part of Web
Platform Wednesday, be sure to note how much time you spent
on any particular property and report that back to the
coordinator.
Also note any issues or concerns you have with the
content and report that back as well.
Also please, please, please tweet, post, or otherwise
communicate through social media channels like Facebook
and G+ and Twitter.
We want to get the word out.
And that completes the exercise.
Thanks for contributing.
Your time and expertise are invaluable.
And your contribution to Web Platform Docs and the greater
community is making the web successful.