search

mozilla / openbadges-backpack

Mozilla Open Badges Backpack
https://backpack.openbadges.org/
Other
862 stars 263 forks source link

Update wiki docs #1023

Closed SueSmith closed 9 years ago

threeqube commented 10 years ago

Draft of new displayer onboarding page https://github.com/mozilla/openbadges/wiki/Open-Badges-Onboarding:-Displayers

This looks good as far as I can tell! :+1:

SueSmith commented 10 years ago

Thanks @threeqube - will have a look through the rest of the wiki.mozilla.org pages and hopefully condense the info into a handful of new pages on here..

threeqube commented 10 years ago

Sounds great @SueSmith

threeqube commented 10 years ago

Checking out https://github.com/mozilla/openbadges/wiki/Verifying-Badges-for-Display

wrt the following:

checking any included expiry date

in this section: https://github.com/mozilla/openbadges/wiki/Verifying-Badges-for-Display#verifying-hosted-badges

@cmcavoy do we do anything with the expiry? I thought we didn't...

SueSmith commented 10 years ago

Just looking through the wiki.mozilla.org pages listed above - have highlighted questions, suggestions etc in bold: https://github.com/mozilla/openbadges/issues/1023#issuecomment-47711139

Thoughts welcome! cc @threeqube @cmcavoy

threeqube commented 10 years ago

@SueSmith will review now.

threeqube commented 10 years ago

Onboarding Earner https://wiki.mozilla.org/Badges/Onboarding-Earner where could this live? badgealliance.org seems more for issuers, displayers etc..

I think this should just be a tutorial on how to use the Mozilla backpack. I think for now, we create a wiki on github and figure out where to house it later.

Get Started https://wiki.mozilla.org/Badges/GetStarted get started info introducing roles etc - could maybe be homepage of developer/ community section on badgealliance.org??

I like that idea. It's a way to direct traffic and point folks in the right direction.

Technology https://wiki.mozilla.org/Badges/Technology this mainly reiterates info on other pages, eg onboarding for issuers, displayers - can we lose it?

Yep, let's get rid of this or skip it.

Backpack https://wiki.mozilla.org/Badges/Backpack not much on there, should probably be superseded by new wiki homepage on openbadges repo?

Yeah, this can be deleted too.

About https://wiki.mozilla.org/Badges/About also repetitive, can probably be replaced with get started stuff above

Works for me.

FAQs https://wiki.mozilla.org/Badges/FAQs needs massively condensed - would this be a possibility on badgealliance.org?

absolutely.

BadgeKit https://wiki.mozilla.org/Badges/badgekit unnecessary with info on badgekit-api and openbadges-badgekit repos..?

Agreed.

Pilot programs https://wiki.mozilla.org/Badges/Pilot_programs can we lose this? seems like badgealliance.org replaces it

Yep this is massively dated.

Team and Tools https://wiki.mozilla.org/Badges/Team_and_Tools same again..?

Yep, dated.

Roadmap https://wiki.mozilla.org/Badges/roadmap and again?

Yep dated.

Infrastructure Technical Documentation https://wiki.mozilla.org/Badges/infrastructure-tech-docs same

Yep agreed. Dated and irrelevant.

Infrastructure Plan https://wiki.mozilla.org/Badges/infrastructure-plan same (these last few seem naturally replaced by badgealliance.org)

Yep agreed.

threeqube commented 10 years ago

We talked briefly about this a while back (mozilla/openbadges-badgekit#268) - I guess moving the info to a new location maybe makes it easier to condense it all and just leave the stuff that isn't relevant any more..??

I think with BadgeKit well documented within its repo, we're all good on this front.

SueSmith commented 10 years ago

Thanks @threeqube - aiming to get any outstanding bits of writing for this stuff drafted tomorrow.

threeqube commented 10 years ago

That sounds great @SueSmith ping me if you need to bounce any thoughts by. Thanks!

SueSmith commented 10 years ago

First draft of earner backpack tutorial: https://github.com/mozilla/openbadges/wiki/Share-your-Badges-with-the-Mozilla-Backpack

I wasn't 100% sure what title I should give it..

p.s. In the screenshots you can see some of the really impressive badges I've awarded myself trying out the issuer API etc :expressionless:

Dumping images...

backpack-upload backpack-badges backpack-badge-detail backpack-collections backpack-issuer-settings backpack-portfolio

threeqube commented 10 years ago

First draft of earner backpack tutorial: https://github.com/mozilla/openbadges/wiki/Share-your-Badges-with-the-Mozilla-Backpack

This looks great. Question:

In the collections section https://github.com/mozilla/openbadges/wiki/Share-your-Badges-with-the-Mozilla-Backpack#collections this part:

"Notice the public checkbox on each collection - if you check this, your badges will be available for embedding in website widgets and other online contexts."

Should we make it explicit, if the public box is checked, it becomes discoverable to displayers via the displayer API? Maybe that's too detailed...

I wasn't 100% sure what title I should give it..

I think this title works great.

p.s. In the screenshots you can see some of the really impressive badges I've awarded myself trying out the issuer API etc :expressionless:

Nice! :+1:

SueSmith commented 10 years ago

Thanks @threeqube - hmm, how about something like:

Your public badges will be discoverable to badge displayers. Badge displayers retrieve the public badges awarded to your email address and present those badges online, in a widget, site or application.

threeqube commented 10 years ago

That sounds good to me. :+1:

SueSmith commented 10 years ago

First (bit rough) draft of get started guide discussed above - just dumped on the github wiki for now https://github.com/mozilla/openbadges/wiki/Get-Started-with-Open-Badges

Will have a longer look through wiki.mozilla.org pages and add more to this page..

p.s. should I update the help/ support info on these pages for email/ twitter etc to badgealliance.org contact info?

threeqube commented 10 years ago

p.s. should I update the help/ support info on these pages for email/ twitter etc to badgealliance.org contact info?

Ah, hmmm...let's keep badges@moz for now and I'll ask @megcolek if she has further thoughts.

threeqube commented 10 years ago

First (bit rough) draft of get started guide discussed above - just dumped on the github wiki for now https://github.com/mozilla/openbadges/wiki/Get-Started-with-Open-Badges

"Open Badges are more granular than many traditional types of credential." can we say "Open badges can be more granular" instead of "are"? Reason being, smaller, more granular badges can roll up to larger badges that represent larger certificates or degrees.

"Issuers can be educational institutions, employers and organizations such as community groups."

I think we should add that issuers can also be individuals.

SueSmith commented 10 years ago

Thanks @threeqube - made those changes.

threeqube commented 10 years ago

Great! Thanks @SueSmith :smiley_cat:

SueSmith commented 10 years ago

Draft of new FAQs page: https://github.com/mozilla/openbadges/wiki/Open-Badges-FAQs

Thinking I'll go through the rest of the wiki.mozilla.org pages next and see if any outstanding bits of info can be fitted into the new docs.. Also thinking the BadgeKit glossary (https://github.com/mozilla/openbadges-badgekit/wiki/Glossary) could probably be repurposed to serve as a general Open Badges glossary whenever we move stuff off the GitHub wikis..?

threeqube commented 10 years ago

Draft of new FAQs page: https://github.com/mozilla/openbadges/wiki/Open-Badges-FAQs

Thanks @SueSmith. Will go through this.

Thinking I'll go through the rest of the wiki.mozilla.org pages next and see if any outstanding bits of info can be fitted into the new docs..

That sounds like a great plan.

Also thinking the BadgeKit glossary (https://github.com/mozilla/openbadges-badgekit/wiki/Glossary) could probably be repurposed to serve as a general Open Badges glossary whenever we move stuff off the GitHub wikis..?

Perfect. Cc-ing @megcolek who is working on overall messaging as part of the Badge Alliance messaging working group.

SueSmith commented 10 years ago

I've streamlined butchered the wiki homepage: https://github.com/mozilla/openbadges/wiki

Moved a chunk of it here: https://github.com/mozilla/openbadges/wiki/I-Want-To-Help (I've just copied and pasted that so not sure how accurate it is - can definitely have a go at updating it if it would be useful..)

Hope that's ok! :tractor:

threeqube commented 10 years ago

Draft of new FAQs page: https://github.com/mozilla/openbadges/wiki/Open-Badges-FAQs

"gamification" is quite the polarizing word. I wonder if we might just do without it...

Another thing I might add is that while resumes and CVs are self-reported, badges are verified that that person actually did the work and earned the badge.

"a range of tools are available to support whichever approach an issuer chooses to take, as is the community, which provides access to a depth of expertise."

Not sure linking to the community site feels right. I feel we've been deprecating that community site for a while now.

a nit here: "the nature of this communication is decided by the issuer, who knows their community of badge earners best." I think this can come off a bit nebulous. Can we say, "the nature of this communication is decided by the issuer whether email or SMS, who knows their community of badge earners best." Just adding a couple concrete examples?

threeqube commented 10 years ago

Overarching note: I wonder if we can have a go at organizing the questions in the FAQ so it fits a cognitive flow. I feel like some of the questions can be bundled together as a group. Happy to have a go at it with you. Let me know what you think. Thanks @SueSmith!

threeqube commented 10 years ago

I've streamlined butchered the wiki homepage: https://github.com/mozilla/openbadges/wiki

Ha! I'll have a look.

Moved a chunk of it here: https://github.com/mozilla/openbadges/wiki/I-Want-To-Help (I've just copied and pasted that so not sure how accurate it is - can definitely have a go at updating it if it would be useful..)

Yep, sounds good.

Hope that's ok! :tractor:

You bet! :construction_worker:

threeqube commented 10 years ago

btw this resource list is pretty awesome: https://github.com/mozilla/openbadges-badgekit/wiki/BadgeKit-and-Open-Badges-Resources :+1:

threeqube commented 10 years ago

I've streamlined butchered the wiki homepage: https://github.com/mozilla/openbadges/wiki

Ha! I'll have a look.

This looks fine imho. :+1:

SueSmith commented 10 years ago

Thanks @threeqube

"gamification" is quite the polarizing word. I wonder if we might just do without it...

Ah I hadn't realised that - got rid of it.

Another thing I might add is that while resumes and CVs are self-reported, badges are verified that that person actually did the work and earned the badge.

Added this:

While a CV or resume is "self-reported", i.e. the individual lists their own experiences and attributes - badges are verified before being displayed. This means that interested parties (e.g. employers) can rest assured that a badge represents a legitimate, authenticated achievement, the nature of which is described within the badge itself, which is also linked to the awarding organization.

Is it ok to say "are verified before being displayed"? Bit unsure on that..

can we also add individuals like teachers tutors, community instructors, coaches, etc?

Added.

Not sure linking to the community site feels right. I feel we've been deprecating that community site for a while now.

I wondered about that.. Changed to link to the Google Groups - is that ok?

In this section https://github.com/mozilla/openbadges/wiki/Open-Badges-FAQs#how-are-badges-created I know you're focusing the documentation specifically on open badges but I wonder if it might be worth mentioning that it's totally up to the issuer to come up with the learning content and assessment of the badge. Once that is done, the open badge is defined within the specification framework. What I think we might need to address, albeit briefly, is that there are a couple processes to creating an open badge; the content creation and the technical badge class/assertion creation. Hope that makes sense.

Totally, that helps to crystallise it.. Changed to this:

The process of creating a badge typically involves two broad tasks:

  • creating a learning or other experience (and optionally assessment)
  • creating a badge to represent that experience within the Open Badges framework

For example, an issuer could define a competency in a subject such as math, then design learning materials for it, assess students with regard to that competency and so on. Once the competency is defined (and the method for learning/ assessing it), the issuer can create a badge to represent the achievement of earning that competency. For non-educational badges, the first task is simply to create or plan the experience you plan to award the badge for.

The process of creating a badge within the Open Badges framework involves designing the image and data, then hosting them for online display. In technical terms, a badge consists of a generic badge class and a badge assertion for each earner who is awarded it. Essentially this means hosting some JSON files and an image file.

Does that sound reasonable?

The question is about badge systems but we point to a list of badge issuers.

Added this:

A host of real-world badging systems exist, supporting badge issuing, collection and display. Badging can be a fairly straightforward, lightweight task, or can be rigorous and involve various processing stages.

A badging system for issuers can include badge image design and metadata creation tools, as well as publishing in HTML, for example if badges are to be made available for earner applications via a website. For issuers using assessment, the ability to review and process applications can also be part of a badging system. Badge collection and display systems primarily focus on handling the data for awarded badges, providing the ability to embed badges within sites, applications and on social media.

Badging systems can involve the following tasks:

  • creating badge classes
    • designing badge images
    • defining badge data items such as descriptions and criteria
    • BadgeKit is an example of this
  • creating badge assertions (i.e. awarding badges)
  • assessing earner applications for badges
    • handling evidence for applications
    • BadgeKit can also handle this
  • collecting the badges a particular earner has been awarded
    • giving the earner control over privacy and visibility
    • the Mozilla Backpack is an example of this
  • writing badges out to a digital context for display or sharing
    • verifying badge authenticity

Maybe the question needs reworded..

I think this can come off a bit nebulous. Can we say, "the nature of this communication is decided by the issuer whether email or SMS, who knows their community of badge earners best." Just adding a couple concrete examples?

Definitely clearer, added.

Just wondering why it's called the "Backpack Baker API" as opposed to just "Baker API"?

God knows why I did that. Changed to Baker API.

I wonder if we can have a go at organizing the questions in the FAQ so it fits a cognitive flow. I feel like some of the questions can be bundled together as a group.

Yes I was wondering how best to organize it as it's a bit messy, will have a go and post back to see what you think..

btw this resource list is pretty awesome

Should probably give that a redraft, did it a while back - I might know what some of the things on it are actually for now :smile_cat:

SueSmith commented 10 years ago

Redrafted resource list: https://github.com/mozilla/openbadges-badgekit/wiki/BadgeKit-and-Open-Badges-Resources

SueSmith commented 10 years ago

I've thrown together a basic tutorial for new issuers: https://github.com/mozilla/openbadges/wiki/New-Issuers:-Give-Yourself-a-Badge

It's intended as a lightweight, slightly simplistic alternative to the Badge Lab tutorial. It basically takes you through the process of creating a new badge (calling it "Rookie Badge Issuer"..), issuing it to yourself, baking it and importing it into your own Mozilla Backpack. I thought working through all of those stages might give new issuers a better sense of the whole picture.. Hope it looks ok!

Dumping images... design-badge valid-assertion baked-badge-download imported-badge

SueSmith commented 10 years ago

Started repurposing the BadgeKit glossary as a general Open Badges glossary: https://github.com/mozilla/openbadges-badgekit/wiki/Glossary

To be continued on an ongoing basis..

SueSmith commented 10 years ago

I've re-organized the FAQs https://github.com/mozilla/openbadges/wiki/Open-Badges-FAQs

Still not sure it's ideal but I guess it could be better organized once we move it off the wiki and onto a proper page..

threeqube commented 10 years ago

@SueSmith thanks and so sorry for the delay!

"gamification" is quite the polarizing word. I wonder if we might just do without it...

Ah I hadn't realised that - got rid of it.

Thanks! :+1:

Added this:

While a CV or resume is "self-reported", i.e. the individual lists their own experiences and attributes - badges are verified before being displayed. This means that interested parties (e.g. employers) can rest assured that a badge represents a legitimate, authenticated achievement, the nature of which is described within the badge itself, which is also linked to the awarding organization.

Is it ok to say "are verified before being displayed"? Bit unsure on that..

Well doesn't our API do that basic level verification of ensuring the badge is connected to the earner? I think it's ok and otherwise looks good imho.

can we also add individuals like teachers tutors, community instructors, coaches, etc?

Added.

Wonderful :fireworks:

Not sure linking to the community site feels right. I feel we've been deprecating that community site for a while now.

I wondered about that.. Changed to link to the Google Groups - is that ok?

Yep, sounds great.

The process of creating a badge typically involves two broad tasks:

  • creating a learning or other experience (and optionally assessment)
  • creating a badge to represent that experience within the Open Badges framework ...

Does that sound reasonable?

Yep this is great.

The question is about badge systems but we point to a list of badge issuers.

Added this: A host of real-world badging systems exist, supporting badge issuing, collection and display. Badging can be a fairly straightforward, lightweight task, or can be rigorous and involve various processing stages....

Maybe the question needs reworded..

I think this is an outstanding response but I think I agree, I think it's not the right question. It seems it should be more like "what does a badge system entail?" or something like that, no? Thoughts?

I think this can come off a bit nebulous. Can we say, "the nature of this communication is decided by the issuer whether email or SMS, who knows their community of badge earners best." Just adding a couple concrete examples?

Definitely clearer, added.

Great!

Just wondering why it's called the "Backpack Baker API" as opposed to just "Baker API"?

God knows why I did that. Changed to Baker API.

:smile:

I wonder if we can have a go at organizing the questions in the FAQ so it fits a cognitive flow. I feel like some of the questions can be bundled together as a group.

Yes I was wondering how best to organize it as it's a bit messy, will have a go and post back to see what you think..

Wonderful. Thanks!

btw this resource list is pretty awesome

Should probably give that a redraft, did it a while back - I might know what some of the things on it are actually for now :smile_cat:

Sounds good. Will have a closer look! :eyes:

threeqube commented 10 years ago

Started repurposing the BadgeKit glossary as a general Open Badges glossary: https://github.com/mozilla/openbadges-badgekit/wiki/Glossary

Note on Directory definition: There's definitely a BadgeKit directory definition but coming down the pike will be a broader directory as per https://github.com/mozilla/openbadges-directory

I'm also noticing some of the terms have narrower, more specific "BadgeKit" definitions like "Issuer"d does while also having broader definitions too. You know what I mean?

To be continued on an ongoing basis..

Sounds like a plan. :+1:

threeqube commented 10 years ago

https://github.com/mozilla/openbadges-badgekit/wiki/Glossary

A bit of me is wondering if we need a separate broader open badges repo glossary as well... I think most of the work is already done here in the BadgeKit glossary but perhaps taking some of the broader definitions out and separately listing them in an open badges glossary? Thoughts:question:

SueSmith commented 10 years ago

Thanks @threeqube - yep definitely agreed, some of the terms have BadgeKit-specific meanings. will go back through the BadgeKit glossary and start a separate general Open Badges one. Will probably copy some of the definitions but should reduce confusion.. I guess when we get to moving this content off the GitHub wikis it'll be easy enough to have them in sensible sections as well, whether it's GitHub Pages sites or whatever..

threeqube commented 10 years ago

@SueSmith yep sounds like a plan. Thanks!

SueSmith commented 10 years ago

First draft of general Open Badges glossary: https://github.com/mozilla/openbadges/wiki/Glossary

Redrafted the BadgeKit one to focus on BadgeKit-specific stuff (also got rid of the verb/ noun thing as it seemed a bit daft in retrospect..): https://github.com/mozilla/openbadges-badgekit/wiki/Glossary

threeqube commented 10 years ago

I've re-organized the FAQs https://github.com/mozilla/openbadges/wiki/Open-Badges-FAQs Still not sure it's ideal but I guess it could be better organized once we move it off the wiki and onto a proper page..

Had a look. I think it's fine. Thanks @SueSmith

threeqube commented 10 years ago

First draft of general Open Badges glossary: https://github.com/mozilla/openbadges/wiki/Glossary

This looks great. I think one missing thing is perhaps Issuing platforms like the credlys, achieverys, basically things on this list: http://wiki.badgealliance.org/index.php/Badge_Issuing_Platforms

Might we add that?

SueSmith commented 10 years ago

@threeqube sure, will do!

threeqube commented 10 years ago

Great! :smile_cat:

threeqube commented 10 years ago

Redrafted the BadgeKit one to focus on BadgeKit-specific stuff (also got rid of the verb/ noun thing as it seemed a bit daft in retrospect..): https://github.com/mozilla/openbadges-badgekit/wiki/Glossary

This looks good. I didn't think the verb/noun thing was daft but this version looks pretty fluid imho. Thanks!

SueSmith commented 10 years ago

Added list of issuing platforms here: https://github.com/mozilla/openbadges/wiki/Glossary#issuer

threeqube commented 10 years ago

Added list of issuing platforms here: https://github.com/mozilla/openbadges/wiki/Glossary#issuer

Looks great. :+1:

threeqube commented 10 years ago

I've thrown together a basic tutorial for new issuers: https://github.com/mozilla/openbadges/wiki/New-Issuers:-Give-Yourself-a-Badge

I totally missed this one in the thread but had a read and I think it's great. One small thought, take it or leave it. In the Create the Badge Image section https://github.com/mozilla/openbadges/wiki/New-Issuers:-Give-Yourself-a-Badge#create-the-badge-image I wonder if it's worth discussing dimensions here as well which is a question I've often fielded. I think we light to encourage issuers to think about seeing the badge down at sizes as small as 50 x 50 to see if the contents are legible and decipherable. Thoughts?

SueSmith commented 10 years ago

I wonder if it's worth discussing dimensions here as well which is a question I've often fielded.

Added this:

When you're working on your badge design, it's recommended that you view the result at 50 x 50px, making sure the content remains legible at that size. The badge may end up being displayed in a variety of contexts - taking care over how it scales will help it to have a consistent appearance wherever people see it.

Image guidance is definitely an easy bit of practical advice that isn't actually represented too often in the docs so will look at other opportunities to mention it.

Wondering if an issuer checklist type thing might be an idea..? Could just list all of the things you have to remember as an issuer without going into much detail, linking to other docs but keeping it short and sweet..? The existing docs are pretty wordy - people could maybe use a reminder/ primer type thing to save them having to plough through all the wordy stuff more than once..

Cheers @threeqube :smile_cat:

threeqube commented 10 years ago

Added this: When you're working on your badge design, it's recommended that you view the result at 50 x 50px, making sure the content remains legible at that size. The badge may end up being displayed in a variety of contexts - taking care over how it scales will help it to have a consistent appearance wherever people see it.

I like this. :+1:

Image guidance is definitely an easy bit of practical advice that isn't actually represented too often in the docs so will look at other opportunities to mention it.

Sounds great.

Wondering if an issuer checklist type thing might be an idea..? Could just list all of the things you have to remember as an issuer without going into much detail, linking to other docs but keeping it short and sweet..? The existing docs are pretty wordy - people could maybe use a reminder/ primer type thing to save them having to plough through all the wordy stuff more than once..

I really like the checklist idea. That'd be great @SueSmith! :koala:

SueSmith commented 10 years ago

@threeqube cool, will draft checklist and let you know how I get on.

Added image guidance to FAQs: https://github.com/mozilla/openbadges/wiki/Open-Badges-FAQs#what-properties-should-a-badge-image-have (I had forgotten about the minimum 90px guidance so have added it too, hope that's still accurate..)

threeqube commented 10 years ago

@threeqube cool, will draft checklist and let you know how I get on.

Sounds great. Thanks!

Added image guidance to FAQs: https://github.com/mozilla/openbadges/wiki/Open-Badges-FAQs#what-properties-should-a-badge-image-have (I had forgotten about the minimum 90px guidance so have added it too, hope that's still accurate..)

:+1: