Re: Organizing information for new contributors

Hello Amelia,

Thanks for taking the time to do such a deep-dive look into the site and to
write up you ideas. I agree faith pretty much everything you've said, and
am actually in the process of addressing a lot of what you are talking
about. The home page is new, replacing what was there before. And I
designed a new navigation bar that we will be rolling out across the whole
site, as you suggest. You've pointed out some good catches that were
bugging me too, but that I hadn't quite remembered in a while — the docs
pages logo should link to the main home page, for example.

So thanks! This is helpful both in finding things we hadn't been thinking
about and in confirming the need to change the ones that are in progress.

I look forward to seeing what else you might want to contribute,
Jen

Jen Simmons
designer, consultant and speaker
host of The Web Ahead
jensimmons.com
5by5.tv/webahead
twitter: jensimmons <http://twitter.com/jensimmons>



On Thu, Apr 10, 2014 at 8:29 PM, Amelia Bellamy-Royds <
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 -- 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?
>
>