662987 - Clean up the Jetpack Wiki page

Status: RESOLVED FIXED

(Add-on SDK Graveyard :: Documentation, defect, P1)

Description

[Will Bamberg [:wbamberg]]

I was looking at the Jetpack Wiki just now, and it occurs to me that it includes:

* things which we hope to be very very useful to users (external tutorials, additional modules, FAQ...)
* things that are important but tend to be inward-facing (processes)
* things that are pretty old and could easily confuse and mislead people

We should figure out what's out of date and move it into a separate page indicating that.

Perhaps we also should to preserve more clearly the difference between Jetpack (the project) and the SDK (the product), and instead create an "Add-on SDK" sub-page off Jetpack, and put all the user-facing SDK stuff there?

But right now I'm a bit worried about sending innocent users there.

Comment 1

[Will Bamberg [:wbamberg]]

There's a first attempt at cleaning up the page here: https://wiki.mozilla.org/Labs/Jetpack-draft .

It's a pretty minimal change, mostly to ensure that all the stuff linked off the main page is current, and that the stuff not current is moved to a new page (https://wiki.mozilla.org/Labs/Jetpack/Historical) and clearly marked as such. There's obviously stuff in there that ought to be updated (l10n for example).

I've split the front page between:
- stuff pointed at people who want to use the SDK/Builder (FAQs, tutorials, examples)
- stuff pointed at people who want to get involved in developing the SDK/Builder (internal processes and guidelines, mostly)

Comment 2

[Will Bamberg [:wbamberg]]

Myk's comments:

It's a good start! But since we have a couple weeks until we release, I'm hoping we can do more extensive gardening of this page.

First thoughts:

    * Focus on project participants, so have little to no content for users, except for a pointer to the product pages for the two products. I wouldn't include the header graphic at all, as it doesn't help us sell the project to participants, and it pushes too much content below the fold. But the mission statement is ok, as it's worth reminding even existing participants about our mission. And the section for users should be something as simple as:

      Add-on Developers
      Just want to use Jetpack technologies to build add-ons?
      Check out the Add-on SDK and Add-on Builder.

    * Prioritize existing participants, as new ones don't stay new for long, but existing ones will return to this page over and over if it provides them useful information. So most of the information should be targeted at existing participants looking for some info they forgot (or don't use often enough to memorize), but we could have a small section targeting new participants that reads something like:

      New Participants
      Want to get involved?
      Talk to us on IRC or in our discussion forum,
      check out existing bugs or file one yourself,
      and read up on contributing code.

    * Embed the most important info directly into the page. For example, instead of just linking to the meetings page, put basic info about the meetings into the page itself, i.e. something like:

      Weekly Meetings
      The project holds weekly public meetings to check status, discuss issues, and plan work.
      Time: Tuesdays at 10:00 A.M. Pacific Time
      In Person: Mozilla HQ, Second Floor, Room JK
      Online: Skype, "mozilla-jetpack" account, ping warner on the #jetpack IRC channel to join
      Last Meeting: Tuesday, June 7 (Minutes)
      Next Meeting: Tuesday, June 14 (Agenda)
      More Info and Archive of Minutes

Comment 3

[Will Bamberg [:wbamberg]]

> 
>     * Focus on project participants, so have little to no content for users,
> ... And the section for users should be something as simple as:
> 
>       Add-on Developers
>       Just want to use Jetpack technologies to build add-ons?
>       Check out the Add-on SDK and Add-on Builder.

We still need somewhere to keep things like the FAQ, the list of extra modules, the list of examples and tutorials, though (those are user-facing, right?). Some of these should arguably live in the doc set (but currently don't, and probably won't in 1.0), but some, it seems to me, belongs better on a Wiki where the barrier to adding new items is low. Do you envisage having these things as AMO pages?

Everything else makes lots of sense.

Comment 4

[Myk Melez [:myk] [@mykmelez]]

(In reply to comment #3)
> We still need somewhere to keep things like the FAQ, the list of extra
> modules, the list of examples and tutorials, though (those are user-facing,
> right?). Some of these should arguably live in the doc set (but currently
> don't, and probably won't in 1.0), but some, it seems to me, belongs better
> on a Wiki where the barrier to adding new items is low. Do you envisage
> having these things as AMO pages?

Perhaps.  Stuff that belongs on a wiki should live in a wiki; I just want to clearly distinguish between project- and user-facing pages.  If we store some user-facing docs on the wiki because a wiki is the best place to host them, it still seems like the main entry point to those docs should be the user-facing docs on AMO.

Comment 5

[Will Bamberg [:wbamberg]]

Attachment: Link to Jetpack project page

I've updated the page and moved it to /Jetpack. Shall I move all the other pages from /Labs and redirect from there? 

e.g. 

/Labs/Jetpack/Presentations -> /Jetpack/Presentations

?

Comment 6

[David Mason [:dcm :dmason]]

Comment on attachment 539901 [details] [diff] [review]
Link to Jetpack project page

Looks great Will - yes, lets go ahead and move the elements over to non-Labs area of the wiki.

Comment 7

[Myk Melez [:myk] [@mykmelez]]

(In reply to comment #6)
> Comment on attachment 539901 [details] [diff] [review] [review]
> Link to Jetpack project page
> 
> Looks great Will - yes, lets go ahead and move the elements over to non-Labs
> area of the wiki.

Erm, could we do this deliberately on a page-by-page basis rather than all at once?  For example, Presentations is clearly something that still makes sense to have, but JEP is obsolete, and I'd rather archive it in place.

Even if the new site is missing some pages when we release next week, that feels better to me than to have a bunch of pages in it that don't make sense anymore.  This is a great opportunity to clean house!

Comment 8

[Will Bamberg [:wbamberg]]

(In reply to comment #7)
> (In reply to comment #6)
> > Comment on attachment 539901 [details] [diff] [review] [review] [review]
> > Link to Jetpack project page
> > 
> > Looks great Will - yes, lets go ahead and move the elements over to non-Labs
> > area of the wiki.
> 
> Erm, could we do this deliberately on a page-by-page basis rather than all
> at once?  For example, Presentations is clearly something that still makes
> sense to have, but JEP is obsolete, and I'd rather archive it in place.
> 
> Even if the new site is missing some pages when we release next week, that
> feels better to me than to have a bunch of pages in it that don't make sense
> anymore.  This is a great opportunity to clean house!

Sure. I've tried to collect all the pages that are obsolete under https://wiki.mozilla.org/Labs/Jetpack/Historical. You can still reach those pages from the main Jetpack page, but they're clearly flagged as not to be trusted. If I leave all of those pages under /Labs/Jetpack, but update all the others, does that sound OK?

Comment 9

[Myk Melez [:myk] [@mykmelez]]

(In reply to comment #8)
> Sure. I've tried to collect all the pages that are obsolete under
> https://wiki.mozilla.org/Labs/Jetpack/Historical. You can still reach those
> pages from the main Jetpack page, but they're clearly flagged as not to be
> trusted. If I leave all of those pages under /Labs/Jetpack, but update all
> the others, does that sound OK?

Sounds like a plan!

Comment 10

[Will Bamberg [:wbamberg]]

Do you know how to move a page using the Wiki? The help (https://wiki.mozilla.org/Help:Renaming_%28moving%29_a_page) suggests: 

With the correct page displayed, click on the "Move" tab near the top of the page. 

Although I've followed the other instructions in there, I don't see the "Move" tab. Perhaps I do not have access to this?

I can make manual redirects easily, but then we don't transfer the editing history (personally I don't think this is a big deal), and I already did this with a couple of pages before I thought of moving.

Comment 11

[Myk Melez [:myk] [@mykmelez]]

I see Move, f.e. on <https://wiki.mozilla.org/Labs/Jetpack/JEP>.  Is it possible that you are currently signed out?

Comment 12

[Will Bamberg [:wbamberg]]

(In reply to comment #11)
> I see Move, f.e. on <https://wiki.mozilla.org/Labs/Jetpack/JEP>.  Is it
> possible that you are currently signed out?

No, I'm logged in and can edit stuff. (I guess it's in the same spot as "Edit"?) I see:     
    Page
    Discussion
    Edit
    History
    Watch
    Refresh

Comment 13

[Myk Melez [:myk] [@mykmelez]]

It's actually between History and Watch.  Here's the list of navigation links I have across the top of the page:

    Page
    Discussion
    Edit
    History
->  Move
    Watch
    Refresh

MediaWiki's "Moving a page" doc <http://www.mediawiki.org/wiki/Help:Moving_a_page> says, "Moving (renaming) a page means giving it another name. This is done by using the "move" tab at the top. The tab is not visible if you are not logged in."

And its "User rights" doc <http://www.mediawiki.org/wiki/Manual:User_rights> says, "move 	allows renaming the titles of unprotected pages (requires the edit right)."

So it's weird that you're not seeing the option.  Perhaps ask IT to check your permissions?  In the meantime, to unblock this work, provide a list of old -> new moves in this bug, and I'll make the changes.

Comment 14

[Will Bamberg [:wbamberg]]

> So it's weird that you're not seeing the option.  Perhaps ask IT to check
> your permissions?

Weird, yes. I'll ask IT. 

> In the meantime, to unblock this work, provide a list of
> old -> new moves in this bug, and I'll make the changes.

Well, I think it's really just all the pages linked off /Jetpack that are currently hosted at Labs/Jetpack. I don't think the hierarchy goes deeper than that except for the weekly meetings, but I'm not sure it makes sense to transfer those as well.

Like I say, I already broke the edit history for FAQ, Presentations and Tutorials, although it should be easily enough fixable since there aren't any divergent edits, yet.

Don't worry about it if you don't have time, though, it does not have to happen today, and it's rote work.

Comment 15

[Will Bamberg [:wbamberg]]

OK, I've got the power, so I can finish it off.