Re: Organizing information for new contributors

Thanks for the feedback & welcomes everyone,

While working this weekend I discovered the Help table-of-contents page (
http://docs.webplatform.org/wiki/Help:Contents, accessible from the Tools
drop-down menu) has many good links including the Style Guide.

I've taken the liberty of extending that list to include the other useful
pages I mentioned previously.

In addition to now having this list accessible from the Tools menu, it
could probably be imported wholesale as a section on the
Editor/Contributor's Guide table of contents page.  With a list of
references to complement the step-by-step introduction, that would make the
easy-to-get-to Editor's Guide page a one-stop-shop for most things a new
contributor needs to get their bearings.

The only thing the help list is really missing is a page explaining the
syntax for using the advanced functionality of the search page.  I've been
doing a lot of site-specific google searches to find all sub-pages of a
given file path...

If anyone knows of an external site describing how to search by topics,
categories, etc. (or is able to create such a page specifically for
webplatform.org!), please add it to the help page mentioned above.

I hope to get a chance to listen in to the weekly meeting tomorrow and get
a better idea of what you're all working on.  In the meantime, I've set my
sights on all things CSS-media-query-related.  I'll send out a separate
email outlining a proposed schema.

Best regards,
--ABR



On 14 April 2014 07:45, Jen Simmons <jen@jensimmons.com> wrote:

> 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?
>>
>>
>