April 2, 2020
Introduction to Web Platform Docs

Introduction to Web Platform Docs


BILL LUAN: Shanghai
GDG is a very interesting developer community. SUSANNAH RAUB: I’m
glad somebody has asked this question. RETO MEIER: This is where
the magic happens. JENNY MURPHY: This is primarily
a question and answer show, so if any
of you out there would like to ask questions. MALE SPEAKER: Open up one
browser and make sure that it worked there. These days, it’s not unusual
for me to have about five different browser windows
open at the same time. CHRIS EPPSTEIN: A good portion
of my front-end development time is spent trying to
figure out how I can best build a feature. And a good portion of that is
spent finding the right website where I can find out
the information I need. MALE SPEAKER: Right now,
there’s a lot of great information that’s out there,
but it’s spread across a bunch of different sites. CHRIS EPPSTEIN: Oftentimes, the
difference between getting that information quickly and
right and getting it wrong can be the difference between
something taking an hour and all day. DIVYA MANIAN: As the web moves
forward, we have different operating systems, different
browsers, different devices, and not just that, the standards
that we use for the Web keep changing rapidly
day in and day out. MICHAEL CHAMPION: It’s hard to
find the documentation for what works across all of them. This is something we all need
to solve together as a community for the web to
be the best it can be. PAUL IRISH: The founding members
of Web Platform Docs have contributed quite a bit
of content to create the foundation for Web
Platform Docs. It’s a new community-driven
site that aims to become a comprehensive source for web
developer documentation. But it’s also an open community,
which means you can contribute by sharing your
knowledge and your experience. MICHAEL CHAMPION: What we need
now is a larger community to get in there and deepen
the content with their own expertise. TIM BERNERS-LEE: Join
in the conversation. Make this website the best. DIVYA MANIAN: Just go to
webplatform.org and sign up. MICHAEL CHAMPION: Share
your expertise. TIM BERNERS-LEE: Make it exactly
just what you and I need for building a web page. PAUL IRISH: Join the
community and start learning and sharing today. PETER LUBBERS: Welcome to the
Chrome channel on Google Developers Live. I’m really excited today to talk
to you about a special episode of webplatform.org,
or Web Platform Docs, as we call it. Today, I’m in the studio. My name is Peter Lubbers. I’m a program manager in the
Google Chrome team in developer relations. And recently we’ve been working
on a lot of the infrastructure and getting
ready for the big announcement. With me in the studio today,
I have Alex Komoroske. Hi, Alex. ALEX KOMOROSKE: Hi. PETER LUBBERS: And Scott Rowe. SCOTT ROWE: Hello. PETER LUBBERS: Alex, tell us a
little bit about the project and– well, first of all, tell
us what you do at Google and what you’ve been doing
for this project. ALEX KOMOROSKE: Sure. I’m a product manager
on Chrome’s Open Web Platform team. I’ve been involved in this
project for a few months now. The point of it, I guess, is
that the Web Platform is this amazingly powerful platform,
and there’s lots of good documentation around, but
it’s all over the place. It’s very hard to find
it in one place. So we thought, well, why don’t
we just create a site that anyone can edit and so that you
can have one place to go to find all the documentation? And a whole bunch of folks
thought this was a great idea. A number of other organizations
are involved from the beginning, which I
think is really exciting. So we just announced it
yesterday, the first step in a very long journey to make this
into the comprehensive site for web developer
documentation. PETER LUBBERS: I think that’s an
important thing we need to talk about a little bit more
is that what you’re finding today is an alpha version. It’s something that
we really– with the different stewards, all
of the different browser vendors and other companies like
Adobe and Nokia and HP really wanted see some content,
put some content out there, and then start developing
it in the open. So not really hiding it and
building something that’s fantastic and release it in 2015
or something like that. ALEX KOMOROSKE: Or earlier. PETER LUBBERS: Right, right. So Scott, what do you do? And what have you done
for this project? So what do you do at Google? SCOTT ROWE: I’m a technical
writer, and I work on Web Platform Docs almost
exclusively. Like the other browser vendors
on the project, we do have some full-time people dedicated
to curating and ensuring the quality of
this documentation. We’re looking at this as a very
high-profile project, and we want it to succeed. PETER LUBBERS: That’s actually
a really good thing. As opposed to other projects
that may have a single writer or a single person behind
it, this is really a collaborative effort. But also, as you point out, we
have all of the stewards have full-time people dedicated
to this great resource. So hopefully, they will also be
able to guide the community in developing more and
more of this content. So about we take a look at the
site and start stepping through it? SCOTT ROWE: Go for it. PETER LUBBERS: So if you look at
the home page, you’ll find, of course, the video that
we opened up with. And, of course, you’ll find
different areas at the top– Docs, we have a forum,
blog, chat, tutorials, and other things. One of the important things
about this is that right now, the real focus is on
the Docs area. So, in fact, when you hear about
this project, you’ll hear the abbreviation WPD– Web Platform Docs– webplatform.org Docs. In fact, if you go there, if you
click on Docs, you’ll end up on the Docs home
page, if you will. This page really has
links to all of the information we have. Scott, do you want to tell us
a little bit about what kind of content you might
expect on the site? SCOTT ROWE: Sure. We break our content into three
basic areas– concepts, reference, and tutorial. That’s pretty standard across
any technical writing effort. Within each of those categories,
we further break the content down into
its component parts. So for the CSS reference
documentation, you will see things like CSS properties
and selectors. And then eventually, you’ll burn
down into a property like this– font size. PETER LUBBERS: Let’s take
a look at that a moment. So you have font size here. As I open that up, I find
a lot of different tags applied to this. We’ll come back to
those later. But you can find an
overview table. You have a syntax area, the
actual values described, examples, and other
information. One of the most valuable things
that I think this project will bring
to the table is a compatibility matrix. And again, this is just to
reiterate, it’s just an alpha version right now. But the nice thing is everybody
can contribute. I’ve gone through many sites
in the past, and there are some great resources out there,
for example, Can I Use. It’s a fantastic resource. I think all of the web
developers that I’ve talked to are pretty much aware of that,
and they use that sometimes on a daily basis. Of course, any of those
resources are fantastic, except you can’t edit them. Many times, I’ve written the
owner of a website saying, actually, this has
been changed. You should include
this browser. And it’s just very hard to
do as a single person. So having help from the entire
community is really powerful. So you can see here
compatibility for desktop and mobile. As I said, this is a
work in progress. But the content has been
seeded to get started. We also have tutorials. So the tutorials area, sort of
a large grouping of content that tells you not just as a
reference topic would about the specific feature, but how
you can really use them. Many times it will include
multiple topics, for example, how you build something using
the audio element or something using a set of features, maybe
canvas and web socket to build a compelling case study,
things like that. So let’s take a look at that. For example, the connectivity
tab, if I open that here, the connectivity feature
here, there’s already three tutorials. As I mentioned, a lot of this
content has been seeded from areas like MDN, from MSDN,
from HTML5 Rocks. Opera has great articles
on web development. All of the stewards have
contributed a lot of the content already to be here. For example, here the Web
Socket tutorial is a Web Socket basics tutorial. It has a little description of
what the problem might be here and code examples and really
allowing you to get started with that. And really, the power of Web
Platform Docs, I think I would sum it up with is one thing,
which is the Edit button. Clicking on Edit opens
up this Edit page. I want to drill into that
a little bit more. Of course, it’s very easy
to edit a small typo. If you see a typo, something
very small or something you know should be rewritten,
go for it. You can literally just
go in this page– and we’ll talk a little bit
more about it in a second. You can really just edit the
page, go to the bottom of the page and type in a little
bit of information about what you edited. If it’s just a typo,
that could be summarized as a minor edit. But if you added a new
paragraph, you can describe what you’ve done for the logs
later and then save it. And that’s done. Your documentation is now
live on the internet. You’ve seen, as I scroll down
this page, there’s a ton of other information. I want to ask Alex, who has been
instrumental in creating some of these templates,
to talk a little bit more about that. ALEX KOMOROSKE: So you’ll notice
that on these pages, you might be expecting just
one big text box. But actually, you see here,
we’ve got form fields that are broken out and more
structured. So what we’ve done is we’ve
created for different article types– so for CSS property
or tutorial, any number of different article types, we
create a form that helps organize that information. We aren’t done yet. Some of them need
some more help. But you can see here, this is a
great example where it makes it more clear where to fill
in the information. One thing to call out as well
on this page is we had this notion of flags. So we know the content
isn’t perfect yet. It’s in a very early state, and
we need everyone’s help to help massage it, make it more
complete and comprehensive. So we have this notion of flags
where you can say, this article is not complete, or this
article has errors, or this article needs
a new title. You can flag these off. If you’ve noticed a problem, and
you don’t want to fix it, you can go in, hit Edit, check
off these boxes up here– you can see them, they’re
called high-level issues in content there– and say, well, this
article is a stub. That will flag it. So if you go look at the page,
you’ll a red bar at the top that this article needs
those changes. And other people can find that
content later and say, I’m in the mood to fix stubs and find a
list of stubs and go and fix them and remove that flag. PETER LUBBERS: That’s really
powerful because what we want it to do is for the community
to help, it needs to be pretty clear– ALEX KOMOROSKE: How. PETER LUBBERS: –how
you can do it. ALEX KOMOROSKE: What
you do, right? PETER LUBBERS: Exactly. So we’ve actually broken that
down into three different areas, so five-minutes tasks– [AUDIO LOST] PETER LUBBERS: –you
would uncheck the compatibility needed. So we want to make it really
easy to get started. You really don’t need to be
super technical to be part of this project. Everyone can help. All you need to do is just
sign up at the top. You get an account, and
you’re rolling. SCOTT ROWE: That’s it. If you want to test
code, there’s code there to test, too. ALEX KOMOROSKE: It’s
addictive, really. You start off, you’re correcting
a few typos. You’re just doing these very
tactical things that take a couple of minutes. And then as you get more
confident, as you do it more often, you take on bigger
and bigger tasks. That’s one of the reasons
we wanted to organize it this way– to help people really get
involved in a way that doesn’t require them to jump
directly into it. PETER LUBBERS: Yeah, it
reminds me, I used to contribute a little bit
here and there to MDN. They had a great system like
that, too, where they would provide these doc sprints. Later, I’ll tell you a little
bit more about some ones that we have coming up as well. So these doc sprints where
basically people are online on IRC channel or actually in a
physical location, and really just coming out and saying,
OK, what do I need to do? Here’s a list of tasks, and
just go through it. Like you said, I found
it pretty addictive. It’s really a great
community effort. ALEX KOMOROSKE: And we already
have the chat channel– PETER LUBBERS: Right. ALEX KOMOROSKE: –and the
mailing list as well. There’s lots of active
discussion on the IRC channel about people like, hey,
how do I fix this? It’s a great place to find
other people to help you figure out how to fix things. PETER LUBBERS: Exactly. So on the Getting Started page,
there is in fact some information about how you
can get connected. So there’s an IRC channel,
a mailing list. All of that’s there. Just take a look at that
Getting Started page. I wanted to go through the Q&A.
On our Google Developers Live page, we have a moderator,
and we have a couple of questions. So let’s take some of those. Some of them will
be pretty quick. The first question
is from Fernando. “Will Web Platform Docs hold
WebGL information?” ALEX KOMOROSKE: That’s
a great question. WebGL is an example of a cutting
edge technology that’s only in some browsers
at the moment. The idea of Web Platform
Docs is to be useful, comprehensive, practical
documentation for folks. In fact, we had this notion
of these pillars, these foundational principles to the
site, which you can see on the site at wpd:pillars. And that’s part of our goal. So we want to be inclusive
about this kind of stuff. If web developers are going to
want to know about these kinds of topics, they should be
included, just clearly flagged to make it clear that
you cannot rely on this in every browser. This is something maybe that’s
not standardized yet, or it’s only in the beginning stages
of standardization, or it’s only in some browsers. So yes, WebGL, we definitely
want to have documented on this site as one example
of many other kinds of technologies. PETER LUBBERS: Just add to
that, if you’re a WebGL expert, please help us
build that content. I think the reaction to this
project has been so good because, look, it’s out there. It’s free information. Everyone can join in. Really the only criticism
you can have is there’s not enough out there. Well, come and help
us make it better. I think what you mentioned also
is an important thing. Because if we get the
documentation about these standards that are in the early
stages out there more, then really we can start
seeing it earlier. We can have more collaboration
about it. And since it’s a cross-vendor
effort, it’s going to be really cool. ALEX KOMOROSKE: Yeah. I’m really excited about that. PETER LUBBERS: Another
question from Eltern. “Will Web Platform Docs be
available in other languages?” The infrastructure is set up
so that, yes, it will be possible to translate it. Of course, right
now at launch– I think there’s actually a
little bit of Spanish content that I noticed in the Docs– ALEX KOMOROSKE: We don’t
have a ton of it. Our intention, of course, is
to have this content be available in many different
languages. We looked at a number of
different ways of doing this. We’re still working
on precisely the final way to do it. But this is definitely
very important. I know we’ve had a number of
folks reach out to us and say, hey, I really want to translate
this into German. It’s like, cool. Hold that thought for a second
as we make sure we get this in place for you to do this. But we definitely
want to have a thriving translation community. PETER LUBBERS: It really comes
back to the point where we said, we want to get it out in
front of the community sooner rather than later. So if that means we don’t
have it translated in 32 languages– ALEX KOMOROSKE: Not yet. PETER LUBBERS: –then we’d
rather have it out there and get the community to
help us build that. ALEX KOMOROSKE: Absolutely. PETER LUBBERS: Another
question from Serge. “From the blog post, Web
Platform Docs is the first and most important piece of
webplatform.org.” That’s a good question about are there
other parts of the site that will be created later on? Do you want to– ALEX KOMOROSKE: So right now,
the focus is definitely Docs. It’s primarily documentation. That’s what we’re starting. But I’m so excited about
webplatform.org because there’s so much more
potential. There’s so many other things. We’re even seeing a little
bit with chat. The IRC channel already has
all these interesting discussions going on about not
just the site, but web development in general. So you can imagine
webplatform.org growing over time to include all kinds of
other things that are relevant to web developers. We don’t know exactly what those
are at this point, but I’m excited by the possibility
of the community helping us figure out what things are going
to be useful and then doing that on this site. Webplatform.org is much bigger
than just documentation, which is already quite big. It’s a very open-ended
sort of promise. I’m really excited about it. PETER LUBBERS: So Scott, maybe
you can answer this question. SCOTT ROWE: I’ll do my best. PETER LUBBERS: Web Platform
being a community, how can I help out anything other than
contributing content? SCOTT ROWE: Well, we certainly
have a lot of ways to do that. You can edit the compatibility
tables. That requires some research
figuring out what features are supported in which browsers. There are a number of flags you
can use on content that don’t have anything to do with
the editing tasks, flags that say this content may be
misplaced, or it may be duplicative or some
such flag as that. The way we’ve shown how the
forms are laid out with the different types of information
to supply, those help you get through that process of
contributing in ways that may involve editing or may not. ALEX KOMOROSKE: There’s
a lot of other stuff you can do as well. As one example, you can look at
the recent changes list on the site and see changes that
are obviously spam and help revert those. You could be someone who just
hangs around the IRC channel and helps answer people’s
questions and help them get started. There’s all kinds of stuff to
do that doesn’t directly involve editing content, but
really helping foster the community and be
a part of that. PETER LUBBERS: Fantastic. Another question from Serge– good questions from
Serge here. “Will there be video content
on the site?” Sorry, actually this
is from Eliah. “Will it be accepted,
endorsed, and promoted on the platform? So video tutorials,
for example. I think the answer is yes. ALEX KOMOROSKE: I believe
so as well. We can’t speak on behalf of
everybody, the whole community obviously, but that sounds
great to me. I think this is the perfect
thing to bring up on the mailing list or on the IRC
channel and discuss with the rest of the community. But this totally fits in with
the mission of the site, so– PETER LUBBERS: Definitely, I
would expect to see that. All right. “What is the planned
scope for Docs? Are server-side technologies
like PHP and Ruby going to be added?” ALEX KOMOROSKE: So when I was
hanging out in the IRC channel a lot yesterday and today, this
question’s come up a lot. At the beginning– again, I can’t speak on behalf
of the entire community,. and it’s up to us as a community to
figure out what the answer to this question is. We were focusing at the
beginning especially on client-side technologies,
so technologies that are implemented in a browser, say. However, there’s all kinds of
documentation that’s relevant to web developers that’s
not just based on what’s in a browser. I think over time, as we see
what’s most useful for the community, that may be the
stuff that’s involved in. At the beginning, you can
imagine just a simple page that points you in the
direction of other documentation sites. But definitely, this is
something that people are interested in. It will be hard to do correctly
because there are so many different things to
include, but I think this is a great example of where the
community can help us set the direction for this
site long term. PETER LUBBERS: Perfect. Another question here. “How long
until the alpha ends and what about beta?”
We don’t have– ALEX KOMOROSKE: The way I would
describe it is we’re using the word “alpha” to
communicate to people that this site is very early. We’ve seeded it with a lot of
great content, but there is so much longer to go before the
site has become the definitive piece, the site for
documentation for web developers. So when we drop that label, when
it becomes a stable, or beta, I don’t think anyone
knows at this point. It really depends on how much
the community can come together to bring the site up
to the level of quality that we all want it to be. That is definitely our goal. Our goal is to get this to be
the definitive source of web developer documentation. When we’re to that point, when
we as a community feel comfortable with that, I can
imagine that we drop that alpha bit from the label. PETER LUBBERS: So to
be determined. Jerome in Toronto asked “what
happens to existing documentation on the web? With Web Platform Docs, we now
have duplicate and redundant documentation. How do I deal with that?” SCOTT ROWE: That’s the current
state of affairs. There is a lot of duplicative
content. What we hope to do over time
is to gradually funnel that into fewer and fewer sources
for people to go to so it isn’t quite so hard
to find things. That’s the purpose of
webplatform.org. ALEX KOMOROSKE: We can’t
speak on behalf of various other sites. Our hope is that by fostering
this community as a central place that people can that, that
everyone can come to and centralize around, that
naturally over time– yes, right now, there’s
duplicated content on different sites. But quite frankly, that’s
been the case for a long time as well. There are many great sites that
effectively duplicate content across different
sites. Our hope is that this Web
Platform Docs can, long term, become the comprehensive
answer where, this is where you go. This is where the content
goes as well. In the short term, of course,
it’s very early. There’s still lots of other
sources of content. PETER LUBBERS: And like I said
earlier on, the biggest feature here is that you
can edit this content. It’s very easy to come across
outdated content. I’ve written a lot of articles
myself, and then two years later, somebody will post on a
blog like, oh, this is so bad, this information. Sure, but it hasn’t
been updated. It was accurate at the time. Especially with these evolving
technologies, that’s a real problem. This stuff happens so fast that
it’s almost impossible to keep up with as a single person
or a single site. SCOTT ROWE: It’s going
to take a village. PETER LUBBERS: Exactly. A web village. OK, so one other question
here from Morgan. “How should compatibility
tables be formatted? Should they list all versions or
the first version where you can use an element
or attribute?” ALEX KOMOROSKE: This is a very
low-level question, but one that’s near and dear to my
heart because I wrote the original template that we’re
using right now for the compatibility tables. Compatibility is a very
interesting question because there’s lots of different ways
to present the information that are useful to people
in different contexts. I don’t think that we have
the answer right now. I think we’ve got a pretty good
stab at the beginning. But this is the kind of thing
that we really want to dive into with the community and help
figure out what is the right way to present
this content? So right now, what you do is you
create a new row for each new sub-piece of support. So the first row is
basic support. You might have, say,
box shadow. Whether or not you support
the insect keyword is a sub-feature of that thing, so
that would have its own row. Ideally, we would have the first
version number of each browser that started
supporting it. One other thing, too, that’s
important is we have this notion of compatibility notes. That’s a table after the
compatibility table that says, hey, just FYI, in Chrome Version
12, there was this weird little hack, a tweak
that didn’t work exactly correctly, so that you still
have this historical record for people who do need to figure
out how precisely it differed in other places. But I’m really looking forward
to working with folks to figure out what the right
format is for this. There’s a lot of different
formats out there for this information. SCOTT ROWE: You can also can
tag content that is– you can set up the compatibility
table to show that when a feature was
supported as prefixed and when it was supported
without prefix. So the question is, well, from
which version onward? And how do I show that in
the compatibility table? The method we’ve been adopting
is the first version of its support is the first version
that you cite. And thereafter, it’s assumed
to be supported. If, however, a subsequent
version is a non-prefixed version, then you have a
different tag to apply there. So maybe we need a tutorial
about using that. ALEX KOMOROSKE: It’s easy to
test and see, hey, does this browser support this
functionality? But you might not know when it
started because it’s back in the mists of time. PETER LUBBERS: True. ALEX KOMOROSKE: So what we’ve
done in the current template is it’s possible to say,
I know it’s supported. I don’t know when it started. And if you want, you can also
fill in more specific information and say, oh,
I know it was supported as of Version 7. But there’s a lot of room to
grow here and to explore different options here. PETER LUBBERS: Great. So I think that gives a
pretty good overview. We’ve answered all
the questions. We’ll come back and we’ll make
another pass through just in case we missed any. The final thing that I wanted to
talk a little bit about is the way you can get started
in the community. So of course, we have
the home page. There’s some links to the
Getting Started document. We’re also planning a bunch
of doc sprints. The first one, actually– shameless plug for the San
Francisco HTML5 user group that I run. We actually have an event
next week that will be live-streamed from San Francisco
talking about web standards and also on how
to help on this project. And after that, we’re announcing
for November 3 with Adobe, we’re launching the first
doc spring This is an on-site doc sprint. But, of course we’ll open it
up to anyone that wants to join online. So it’s going to be
pretty exciting. We’re just going to get in the
room for a day and start going through issues. Like I said, we have five-minute
tasks, half-hour tasks, and then the slightly
longer ones. Hopefully, get a bunch of
those out of the way. So anything– ALEX KOMOROSKE: There’s a list
of those on the site as well. PETER LUBBERS: That’s right. ALEX KOMOROSKE: One thing I
wanted to emphasize, too, is there are people who are
organizing these events like Adobe and Peter and others. But really, we want to encourage
you guys to create your own as well. You don’t have to wait for one
of the stewards or something to do this. This is something where if you
want to just grab a few people in your hometown or whatever
and work on it together, that’s great. Let us know on the IRC channels
so we can make sure we’re around to support
you guys. We want everyone in the
community to feel the ability to get this stuff started. PETER LUBBERS: That’s
a very good point. Of course, we’re going to
share the pros and cons, everything we’ve done and the
things that went well and the things that didn’t go well. But everyone should
be able to– we shouldn’t have to wait until
the third of November to start helping, definitely. Well, with that, I think we’re
going to close it for today. Thanks for joining us. The recording of this session
will be available at the same URL in a few minutes so you
can point people to that. Hopefully, we’ll see you online
in the IRC channel helping out on Web
Platform Docs. Thanks so much.

1 thought on “Introduction to Web Platform Docs

  1. problem google circles attack as I have 250 million on corp American Express card send my team in now shut down yahoo.ca permission granted

Leave a Reply

Your email address will not be published. Required fields are marked *