Re: Organizing information for new contributors

Hi, Brian! We can always use a keen editorial eye. Don’t hesitate to ask any questions for technical clarity here or on the freenode IRC channel #webplatform. Welcome! Julee

-------------------
Julee Burdekin
Content Strategist
Adobe Web Platform
@adobejulee
julee@adobe.com

From: "Brian J. Hong" <hong.brian.j@gmail.com<mailto:hong.brian.j@gmail.com>>
Date: Sunday, April 13, 2014 at 4:58 PM
To: Renoir Boulanger <renoir@w3.org<mailto:renoir@w3.org>>
Cc: Amelia Bellamy-Royds <amelia.bellamy.royds@gmail.com<mailto:amelia.bellamy.royds@gmail.com>>, WebPlatform Public List <public-webplatform@w3.org<mailto:public-webplatform@w3.org>>
Subject: Re: Fwd: Organizing information for new contributors
Resent-From: WebPlatform Public List <public-webplatform@w3.org<mailto:public-webplatform@w3.org>>
Resent-Date: Monday, April 14, 2014 at 6:01 AM

Hi Everyone!

I thought I'd tag along in this newcomers thread and introduce myself as well.

I'm mostly a writer by trade; I can probably contribute the most in copy editing and style for English.

Good to meet everyone! I'm always encouraged by your hard work to help the community. Apologies in advance for any tech faux pas I may commit :X

Best,
Brian


On Sat, Apr 12, 2014 at 11:04 AM, Renoir Boulanger <renoir@w3.org<mailto:renoir@w3.org>> wrote:
Hi Amelia,

This is a very thorough email :). We are glad that you want to help and you are welcome to give feedback!

I'm the resident maintainer of the site and I take care of most of the maintenance through the multiple applications we are running. Besides making sure the site is up, my job is also to ensure that nothing is forgotten so we can rebuild from scratch all of the infrastructure.

It means that to do "something", I have to touch many layers; servers, their relationships, their running systems and configurations.

I could talk more about what i'm up to and what is coming but i'm currently at PyCon.

If you want to learn more and join us in the organization and the efforts, you are most welcome in our weekly community meetings.

Looking forward to working with you
--
Renoir Boulanger | Developer operations engineer
W3C | webplatform.org<http://webplatform.org>

http://w3.org/people/#renoirb ✪ https://renoirboulanger.com ✪ @renoirb
~


On April 10, 2014 8:29:40 PM EDT, Amelia Bellamy-Royds <amelia.bellamy.royds@gmail.com<mailto:amelia.bellamy..royds@gmail.com>> wrote:
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<http://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?