Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Already on GitHub? Sign in to your account

Diagrams: Add simple diagrams for service operations #243

Open
frommww opened this Issue Nov 5, 2012 · 5 comments

Comments

Projects
None yet
4 participants
Contributor

frommww commented Nov 5, 2012

Add simple diagrams for service features/capabilities.

Worker

  • upload
  • queue
  • schedule
  • delay
  • timeout
  • payload (payload size)
  • code libraries
  • binary (x64)

Queue

  • push
  • get
  • delete
  • delay

etc.

@dstaley dstaley was assigned Nov 5, 2012

Contributor

frommww commented Nov 5, 2012

Here's an example of why.

-------- Original Message --------
Subject: Fwd: Iron.io - Feedback Request
Date: Mon, 5 Nov 2012 09:36:12 -0800

FYI, we do support timeouts: http://dev.iron.io/worker/reference/api/#queue_a_task

---------- Forwarded message ----------
Subject: Re: Iron.io - Feedback Request
Date: Mon, Nov 5, 2012 at 9:21 AM

It's a very interesting product, the main issue I have is I need IronWorkers to have a hard execution deadline, let's say 30 seconds, that I can set via API or in the Admin panel. The Node.js (and some Node.js plugins) can sometimes run on for 45 minutes or more and I've been unable to come up with a surefire method of avoiding overages.
Other than that, your service is amazing.

Contributor

paddycarver commented Nov 5, 2012

I think we can also improve on this by talking about it in our product overviews. Maybe a second page, or advanced section or something. I'll think on that as I rebuild the worker page. Need to find a balance between overwhelming the user with all our features right up front and users not knowing about our features. The first scares people away, the second leads to situations like this. Really need to find a better way to guide the user through a trajectory from basics to every API option.

Contributor

dstaley commented Nov 6, 2012

After looking into this myself, I don't know how diagrams (visuals) would help users discover a parameter, especially since this particular user was working with raw POST requests. I could see the value in at least showing an example with all the parameters used. Looking back, the "Writing Workers in Node.js" clearly shows how to queue a worker, but it doesn't even hint that there are other options.

Contributor

treeder commented Nov 6, 2012

Agree, I don't think we need diagrams, they just need to be able to find the options. A link to the api docs would probably suffice.

Contributor

dstaley commented Nov 6, 2012

@treeder We have a link at the moment in the first few sentences, but by the time the user gets to the "Queue a task" they've probably forgotten. I think that for Node.js (and any other language that works with POST requests and JSON data) should have a more prominent connection to the API documentation. Paddy and I have a few ideas, namely more interactive API documentation that might be able to help with this, but those are pretty far down the pipeline.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment