Re: Fwd: Organizing information for new contributors

Hi Amelia!

Welcome! and thanks for sharing your observations as a new contributor. 
These are very helpful, and I'm in favor of doing all of them.

Jen Simmons might have a response about the header nav inconsistency.


Cheers,
Janet


On 4/10/14 7:29 PM, Amelia Bellamy-Royds 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?
>

-- 
Janet Swisher <mailto:jREMOVEswisher@mozilla.com>
Mozilla Developer Network <https://developer.mozilla.org>
Developer Relations Community Organizer