W3C home > Mailing lists > Public > public-webplatform@w3.org > April 2014

Fwd: Organizing information for new contributors

From: Amelia Bellamy-Royds <amelia.bellamy.royds@gmail.com>
Date: Thu, 10 Apr 2014 18:29:40 -0600
Message-ID: <CAFDDJ7xrmto5W-U+4X1uSo9pmAMzps+gGrzQEfLE1sKxM__Z3w@mail.gmail.com>
To: public-webplatform@w3.org
Hello all,

My name is Amelia, and although I'm still relatively new to the world of
coding for the web, I'm a firm believer in the philosophy that you don't
fully understand a subject until you can explain it to someone else.  So
while I've been teaching myself web programming over this past year, I have
also been active on Stack Overflow answering other people's questions and
creating demos and tutorials on CodePen.  A recent comment from another
Stack Overflow user suggested that my explanatory skills could make a more
lasting impact contributing to the Web Platform project.

I'd come across the docs previously as a learner, and liked the idea of
having a browser-independent reference source, but hadn't found it yet
ready as a reliable reference.  Now that I'm more confident with my own
understanding of many areas of the material, I've been poking around the
site this week trying to figure out how best to contribute (and making a
few small edits where I can).

In doing so, I've stumbled across many useful pages or pieces of
information geared towards new contributors -- and then found it difficult
to find them again when I need them as reference!

While this experience is fresh in my mind, I thought I'd sum up all the
things that I've found useful as a new contributor, and my suggestions for
making them easier to find.  I'd be happy to make some of these changes
myself (to the extent they are do-able by a new user with limited
permissions), but they are the sort of major re-organization that I
wouldn't want to do without discussion with the established community.

* The Web Platform home page, http://www.webplatform.org/

A good overview of the project, current status/priorities, and plenty of
hints about how to get involved.  However, it's a little difficult to find
once you're inside docs.webplatform.org -- the only link back is through
the breadcrumbs.

My suggestion: make the big "W" logo on each page redirect back to the home
page.  (It currently links to the doc main page, but there is always a
"DOCS" navigation link right beside it that does the same thing.)

* The Docs Main Page, http://docs.webplatform.org/wiki/Main_Page

Currently a bit of a multi-purpose page, serving both as the main table of
contents for the docs as well as a bit of an "About" page for the project.
 Since most of the second type of content duplicates material from the home
page, it might be worth considering removing it from here or shifting it to
a dedicated About page. Removing it could be problematic for the translated
versions, since the web platform home page is English only.

On that note:  Although the English version is easy to get to from anywhere
in the main site (just hit the "DOCS" link in the header), the only way to
get back to a translated main page is through the breadcrumbs.  Is there
anyway to over-ride the header links while inside a translated version?
 There are already more than enough links that bump people back to English
-- when there *is* a translated version of a page it should be easy to find!

* The Editor's Guide, http://docs.webplatform.org/wiki/WPD:Editors_Guide

I saw a mention that you're planning to rename this the "Contributor's
Guide".  I definitely support that -- "Editor" suggests a
top-level/administrative function -- but otherwise this is great content
and easy to find.  The only thing I would change would be to add in a
section at the top that links to the following hard-to-find pages for
contributors:

  -> The "Getting Started" Page,
http://docs.webplatform.org/wiki/WPD:Getting_Started

      This page needs to be cleaned up (the tables are random), but is
great content for new contributors.  It deserves more prominence than a
link from Step 3 of the Guide.

  -> The "Projects" Page, http://docs.webplatform.org/wiki/WPD:Projects

     This page could use a little more information (is there a template
that could grab the last-modified date and summaries for the linked
sub-pages?) and of course it would need to be kept-up-to-date, but a page
like this, showing active projects and goals and required tasks to achieve
them, would be great for helping new contributors get oriented.

    Currently, there are a number of links around the site to the "Web
Platform Wednesdays" pages.  However, since regularly scheduled activities
don't seem to be sustainable long term, maybe those should all be re-routed
to the Projects page, and the WPW projects be integrated within it.   The
idea of having specific projects with clearly defined tasks and a
coordinator who can be a contact point for new contributors is great, but
having it linked to a specific date can make it look stale and out-of-date
quickly.

* Filing Bugs, http://docs.webplatform.org/wiki/WPD:Filing_Bugs

The only link I've discovered to this very useful page is within body text
at the bottom of the main docs and community pages.  Would it make sense to
have the "ISSUES" link in the navigation header redirect here instead of
going straight to the project issue tracker?  Or would that be frustrating
for regular users who already know how to report bugs and just want to go
straight to the bug list?

At the very least, there should be a link to this page from the top of
http://project.webplatform.org/ (if possible), to provide context and
guidance for anyone who follows the "ISSUES" link to report a simple bug.

*** Other Notes ***

* Get rid of or update the Discussion Page, http://www.webplatform.org/talk/

This is one page which I DON'T find useful, in fact I find it problematic.
 It isn't up-to-date (doesn't have the link to the web client for IRC) but
even if it was, the material is all already covered, with better context,
in Step 2 of the Editor's Guide (
http://docs.webplatform.org/wiki/WPD:Editors_Guide/step_2_communicate_with_the_online_community)
 and in the "Community" page (http://docs.webplatform.org/wiki/WPD:Community).


Does anyone have any reason for keeping this page alive, let alone in the
header navigation?  I really don't see it adding anything to the Community
page.

* Header navigation:

Currently, some pages have a header navigation bar with the options

   THE DOCS / CONNECT / CONTRIBUTE / BLOG

while others have

  DOCS / EDITING / DISCUSSION / BLOG / COMMUNITY / ISSUES

As I mentioned above, I don't think the "DISCUSSION" page is adding
anything useful.  I also think the name "CONTRIBUTE" is better than
"EDITING", and "CONNECT" may be clearer than "COMMUNITY".  But whichever
headers are chosen, there should be consistency across the site!

Any other perspectives on which version should be made universal?
Received on Friday, 11 April 2014 12:18:50 UTC

This archive was generated by hypermail 2.3.1 : Tuesday, 6 January 2015 21:20:58 UTC