Seneca Documentation requests

doc-requests.md

We are in the process of updating our documentation and want to ensure that we are providing valuable resources for the Seneca community.

This would be a great place to gather feedback from the community on any areas they wish to see documented.

Following gitter discussion:
After 3 weeks on Seneca this is my take on the project:

• Good parts: pattern matching, act, add. I think these are the mainly selling points of the platform, so I think the getting started should be quite clear here: what are? why are they really effective in a microservice architecture?
• ugly part: error management, plugin states. It would be great to have a curated list of plugins and a better documentation about the options available during seneca startup (e.g debug undead) act (false$:true) and add
• bad part: entities. I really don't understand the use case. It seems that everyone just use it for basic usage then they go through native$ non sense. Can you add some simple why, where, what descriptions to make it clear? e.g. I really don't understand if I have to use ACT to work on an entity. if not, why this is part of the platform?

Oh, another one: it seems that every projects uses a sort of template for the Readme. Well, this is good, but I think this template should be made more simple to read: it is useless to keep the seneca logo on the top and yes, I know that this plugin is part of the seneca framework. These are notes that should be pushed at the bottom. As a developer I need to make my decision, try and fail fast. So I need to be able to take a quick glance over the Readme: About (what and when), then install and then how to use (how and where) . Finally why and who.

thanks for the feedback @pibi much appreciated

• Document all methods (has, list,… see: http://senecajs.org/annotations/seneca.html)
• Make clear that a "plugin factory" is not called directly. So for eg, seneca.has should be called in seneca.ready (see code below)

var Seneca = require('seneca');

var fooAction = function (args, done) {
  done('bar');
};

var plugin = function () {
  this.add({role: 'plugin', cmd: 'foo'}, fooAction);
};

var seneca = Seneca()
  .use(plugin)
  .add({role: 'action', cmd: 'foo'}, fooAction);

console.log(seneca.has({role: 'plugin', cmd: 'foo'})); // false
console.log(seneca.has({role: 'action', cmd: 'foo'})); // true

seneca.ready(function () {
  console.log(seneca.has({role: 'plugin', cmd: 'foo'})); // true
  console.log(seneca.has({role: 'action', cmd: 'foo'})); // true
});

Only simple examples and documentation which only gives a small side of the story are available. Make the canvas bigger if possible:

• Like seneca in a production setup, what all configurations and setup are likely to be done. Best practices.
• Docker seneca combination.
• Security architecture
• Architectures in production environment like choosing different scenarios and explaining what's the best thing to do. For eg, like I need to do photo upload, and I'm planning on using a proxy for serving content. I think it'll be a bad idea to be forwarding that data to the microservices. Okay then I'll keep the copy somewhere and send only a reference to the microservices, then where do I really keep the real data. How do I manage the credentials to the actual storage which is most likely to be held my a microservice somewhere. Questions like this. When we can see how you people manage a couple of situations like this, it'll be great :)

Sorry, not an expert myself, but that's why I'm here in the first place :) - just blurting out whatever came to mind. In short more PRACTICAL scenarios based on PRODUCTION setup.

thanks guys this is all very useful to us