Plugin documentation is lacking

[See original issue on GitLab](https://gitlab.com/BuildStream/buildstream/-/issues/1192)
In GitLab by [[Gitlab user @cs-shadow]](https://gitlab.com/cs-shadow) on Nov 6, 2019, 19:30

## 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](https://docs.buildstream.build/master/elements/stack.html) 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

[//]: # (Acceptance criteria should follow the S.M.A.R.T. principle https://en.wikipedia.org/wiki/SMART_criteria )

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

----
[//]: # (To review information about possible relevant labels for this issue please view the list of labels: https://gitlab.com/BuildStream/buildstream/labels)

Start with the existing plugin documentation, especially the stack element page linked in the issue, and review what information is currently provided for common plugins. Define a consistent documentation structure and expand selected plugins until a reasonably new BuildStream user can understand how to use them.

Written by the indexing model from the issue text.