Plugin documentation is lacking

Background

Plugins are at the heart of BuildStream when it comes to end-users, as that is what allows users to write their element configuration. However BuildStream documentation appears to be lacking in this department. We do have some documentation for each plugin where we talk a bit about default variables. But, just describing what those variables mean in one sentence is hardly sufficient for a new user.

Take stack element for example, it's documentation says just one sentence:

Stack elements are simply a symbolic element used for representing a logical group of elements.

Just by reading that one sentence, it's not clear at all how should an user go about writing a stack element.

Task description

I think we first need to think more seriously about what to document. Next, maybe start with a couple of common plugins and have a more detailed documentation for them. Once we are happy with the general strucutre, we can follow similar format in other plugins as well.

Acceptance Criteria

A resonably new BuildStream user should be able to understand how to use a given plugin by reading its documentation.

---