Developer documentation streamlining.

[SueSmith]

Really just hoping to start a conversation about how people access developer documentation across all of the Open Badges tools and resources. I think it's generally agreed that the adoption process is made trickier by how many different places the documentation is stored at, so I'd like to see if this can be addressed (for reference see the comments in this discussion on the Google Dev Group https://groups.google.com/forum/#!topic/openbadges-dev/Ptefa-X7Kds).

Apologies if any of this has already been discussed, or if I'm suggesting things that have been ruled out/ aren't possible for some reason I don't know about..!

A few initial thoughts from someone new to all of this:

• The official resources are in lots of different places:
  • OpenBadges.org
  • including community site, blog
  • GitHub
  • including lots of repos
  • wiki.mozilla.org

People may land on any of these for the first time completely new to badges - suggested steps:

• establish a consistent approach to orient a person wherever they land
• audit/ redraft the docs on all Open Badges repos (with particular attention to readme and wiki homepages) making it clear where you are and where to go if you're in the wrong place.

I wonder if the OpenBadges.org menu links/ sections are also confusing to people new to badging:

• Earn, Issue, Display
  • Both Earn and Display appear to be pitched at the earner perspective, as opposed to the onboarding docs (wiki.mozilla.org) which speak to each role.
  • Would a "develop" or "developers" menu item be worth considering? It would begin with a concise overview of what developers can do with Open Badges, linking to appropriate resources (some of this is in the community section but I'm not sure I would look there for developer resources automatically).
• Community is also split into three:
  • Learn, Design, Code (code probably corresponds to "develop" mentioned above).

The site structure indicates all of these roles: earn, issue, display, learn, design, code.

Is there any way we could simplify this? Is it ridiculously simplistic to say earners (and maybe consumers) are in one camp and everyone else is in another (people involved in issuing, displaying, developing and so on)? Earners and Badgers?

If you're still reading then you've probably stuck with this longer than I would have! :astonished:

[SueSmith]

Having pondered OpenBadges.org a little more, here's what I'm thinking (hope this is an ok conversation for me to be having :confused:):

• Earner info makes sense primarily on OpenBadges.org (backed up with wiki.mozilla.org info).
• Issue and Display sections - is there a case for getting rid of these and condensing the info into Earn, Community and a new Develop section?
  • This would mean OpenBadges.org would have earner info on the homepage, About page and Earn page. Some of what's in Display could be moved to the Earn section.
  • The Develop and Community pages would include what's in Issue and Display (and some of what's in Community might move to Develop).
  • The Community site could possibly also benefit from being restructured, presumably involving a wider conversation with the badges community. I understand it makes sense for developer info to be here but I think I'd expect a more direct link to development resources on hitting the site..

It seems to me that on first visit, people could be streamlined in two broad groups:

• Earners and those we've been referring to as Consumers (these are both end-users for want of a better description).
• People looking to get involved in badging (issuers, displayers, developers, designers etc).

The first group (earners and consumers) would mainly be interested in the info on the OpenBadges.org site. The other group would be interested in the Develop and Community sections, possibly both - and would be directed to the info in other locations (GitHub etc).

Here are a few examples of sites where there is a link to developer resources on the homepage:

• https://credly.com/ The Credly site does streamlining really well, particularly for developer resources.
• https://groupme.com/
• https://www.flickr.com/

I know things are slightly more complicated for Open Badges with there being the infrastructure and "application" levels (plus the badging community) but I still think access to developer resources could be simplified..

Just realized I should maybe be doing this here https://github.com/mozilla/openbadges.org ??

Is it worth opening the developer documentation conversation up to the Google Dev Group for input?

Again, I'm fully aware that there are probably issues I don't know about in all of this!

cc @threeqube @cmcavoy

[cmcavoy]

Great thinking @SueSmith wanted to also /cc @emgollie

My preference would be to have a single canonical documentation site, probably openbadges.org or community.openbadges.org, and then point everything else there. Revise the README's on Github to center around installing the software, remove the Github wiki's, and have a /docs section in each project that has versioned API details.

[threeqube]

Agreed @SueSmith thanks for leading the charge on this. I think the single canonical site would have to be openbadges.org. It's the namesake and gets a good amount of initial traffic.

If we agree around openbadges.org, then agreed, we should have a dev section in there and as @cmcavoy mentions, point everything with updated documentation there.

openbadges.org as well as community.openbadges.org is actually a wordpress site and we're happy to give you access to it.

[emgollie]

Thanks @SueSmith. The community site links to documentation (http://community.openbadges.org/#code ), and I agree on hosting these doc details from openbadges.org. Happy to discuss further.