Documentation should be restructured for different audiences

[amv]

I propose that the documentation will be restructured to cater to 4 different types of readers:

1. "End user" programmer who is using a gearsloth system provided by sysadmins.
2. "Sysadmin" who is setting up a gearsloth system for others to use.
3. "Advanced end user" programmer who wants to create a custom controller.
4. "A contributor" who wants to fix bugs, create adapters, submit more tests or generally understand the system more deeply before using it.

For "end user" the important things would include:

• Understand the basics of how gearman works.
• Understand the different types of guarantees that the injector can give.
• Understand the task definition.
• Know the gearman injector function name.
• Understand how to pass the task definition to the gearman injector function.

For the "sysadmin" the important things would include:

• All of the "end user" stuff.
• Understand the different types of guarantees that different gearsloth setups can allow the injector function to give.
• Understand how to evaluate which setup is needed for the use case at hand.
• Get straightforward instructions on how to deploy a given setup.
• Understand what kind of maintenance the setup needs and what are the expected error conditions (or partial error conditions) that the setup can end up in.

For the "advanced end user" the important thing would include:

• All of the "end user" stuff.
• Understand how a controller receives a task definition.
• Understand how a controller signals about the task completion.

For the "contributor" we should have at least:

• Documentation of all external interfaces of each component.
• Documentation of adapter interfaces.
• A roadmap for further development targets.
• A who is who description of the key contributors.
• Description of the background philosophy of why the project exists.

[iarna]

Reading the existing documentation I had some issues with it. I found it rather opaque– that is, hard to get it into my head. It start swith an architecture overview which I really don't care about when I'm first reading the docs. Worse, that architecture introduces new jargon.

Think about how unix man pages are usually laid out– I think there's a lot to be said for their organization.

Having it start with a focus on how to use it would be particularly helpful.

For instance, I'd like to see https://github.com/meetings/gearsloth/blob/master/examples/json-client.js embeded in the documentation, along, perhaps, with a note about what it does, eg "Execute the 'log' job with a payload of 'kitteh' in one second"

I'm a bit confused by https://github.com/meetings/gearsloth/blob/master/examples/json-worker.js though… isn't submitJobDelayed provided by gearsloth? Shouldn't the worker be for the 'log' function?

The audience break out suggested would go a long way to improving the documentation I think. I would highly recommend putting those into separate files though. Having them together means people don't have an easy and obvious way of knowing when they're done reading.