search

OpenWorksGroup / openbadges-directory

Mozilla Public License 2.0
12 stars 9 forks source link

Update documentation #51

Closed threeqube closed 9 years ago

threeqube commented 10 years ago

Use this documentation as foundation: http://mozilla.github.io/openbadges-directory/

SueSmith commented 10 years ago

@threeqube great, will update here with progress..

threeqube commented 10 years ago

:+1: sounds like a plan. :smile_cat:

SueSmith commented 10 years ago

Working on docs here: http://suesmith.github.io/openbadges-directory

Initial redraft of existing content done, still to do:

Can do any required updates to the docs in the repo itself on another branch (e.g. for the readme or swagger stuff..).

kayaelle commented 10 years ago

This is great - will touch base late Mon or early Tues.

One update I just made to the api. The response for /tags changed to:

{ "data": [{ "tag":"education", "count":107 }, { "tag":"arts", "count":21 }, { "tag":"leadership", "count":19 }] }

Thanks & have a great weekend!

On Sep 5, 2014, at 4:07 PM, Sue Smith notifications@github.com wrote:

Working on docs here: http://suesmith.github.io/openbadges-directory

Initial redraft of existing content done, still to do:

more detailed tutorial-style content on each API endpoint with examples of request/ response in site/ application code more on exposing your badge list endpoint covering BadgeKit and other examples in site/ application code registering using /register API? Can do any required updates to the docs in the repo itself on another branch (e.g. for the readme or swagger stuff..).

— Reply to this email directly or view it on GitHub.

SueSmith commented 10 years ago

Thanks @kayaelle - tags section updated http://suesmith.github.io/openbadges-directory/directory-api#tags

Hoping to get stuck into some tutorial-type stuff today..

SueSmith commented 10 years ago

First tutorial on /recent endpoint (started there for simplicity): http://suesmith.github.io/openbadges-directory/get-recent-badges

The example code I've included is in node.js and php, I thought the inclusion of php might make it a bit more accessible to a wider range of developers..

@kayaelle feedback welcome! If this looks like an ok approach I should be able to rattle through similar tutorials for the other endpoints fairly quickly..?

Dumping an image.. dir-recent

SueSmith commented 10 years ago

p.s. Any relative links on my fork are currently pointing at https://github.com/mozilla/openbadges-directory since I've used this syntax:

<a href="{{ site.url }}{{ post.url }}/page">

This means that the links are pointing at pages that aren't there yet - thought it best if I don't fiddle around with the config (which I think I'd need to do to make the links resolve correctly when viewing on my GitHub IO as well as when merged..) Should be fine when merged anyway (I think) :confounded:

SueSmith commented 10 years ago

Hmm, forget what I said about relative links, just using the page name on its own (as normal) seems to be working now..

SueSmith commented 10 years ago

Couple more tutorial drafts:

Image dump.. directory-search directory-tags

kayaelle commented 10 years ago

@SueSmith This is all looking great! What do you think about merging today or tomorrow morning?

I haven't fixed location search yet. It works via the api but not via swagger because swagger is doing its own encoding that breaks the search. Location isn't really needed for the api just yet but at some point it may be helpful. It's in the issues list for now.

We'll be adding sort options - alpha by name, alpha by issuer. Doubtful it will get in by tomorrow. Also on the list.

A couple of things that wasn't in the originally documentation is that we're using ElasticSearch and that we're hosting on a free heroku instance. Also for limits - the default is 10, the max is 100. We're limiting due to being on the free heroku site.

SueSmith commented 10 years ago

Thanks @kayaelle - sounds good, will add those wee bits you've mentioned to the docs and open a pull request..

SueSmith commented 10 years ago

Added mention of ElasticSearch, heroku and limit stuff - opened PR https://github.com/mozilla/openbadges-directory/pull/58

@kayaelle FYI am looking forward to coming to the community call/ tech panel tomorrow, but have a few things on during the day (UK time) so will probably not be around until just before the call at 12 EDT.. Will have some time before I head out in the morning so feel free to let me know today/ tonight if there's anything else I can do, will pick up emails etc in the morning.. :smile_cat:

SueSmith commented 10 years ago

Just starting to draft a guide on using the location endpoint, including an example of writing out a link to the badge criteria (should probably add that to the other guides..).

Dumping image.. directory-location

SueSmith commented 10 years ago

Draft of location tutorial http://suesmith.github.io/openbadges-directory/badge-from-location

SueSmith commented 10 years ago

Following the community call etc I've added a bit more explanatory content to the docs:

Who is the Directory for?

How Does it Work?

SueSmith commented 10 years ago

Started a guide on the badge list endpoint http://suesmith.github.io/openbadges-directory/badgelist-endpoint

Hope I've got the BadgeKit part right..?

Still to add a couple of bits explaining/ showing how you could build the badge list in other cases, e.g. if you were retrieving the badge classes from a MySQL database, writing out the JSON badge list array in PHP/ node..

SueSmith commented 10 years ago

Added an example of creating the badge list endpoint in PHP http://suesmith.github.io/openbadges-directory/badgelist-endpoint#php-example

Still to add a node version.

SueSmith commented 10 years ago

Added a node.js example of creating the badge list: http://suesmith.github.io/openbadges-directory/badgelist-endpoint#node-example

In this and the PHP example I've written the code as if the user has their badge class location info in a MySQL database. Happy to cover any other typical scenarios..?

SueSmith commented 10 years ago

Guide to using /register endpoint http://suesmith.github.io/openbadges-directory/register-via-api

(Since I haven't tried this one am just going by the readme..)

SueSmith commented 10 years ago

Just adding some support info to the docs homepage http://suesmith.github.io/openbadges-directory/#help

I've used most of the details from the standard support section on the Open Badges docs - not sure if they should be any different (in particular am wondering about the email address) - this is it:

Help and Support

kayaelle commented 10 years ago

Hi @SueSmith - thanks for all of this. I've been working on standards stuff this week and haven't gotten to this. I'll take a look on Monday.