Designing glossary of terms #1352

mbbroberg · 2016-11-15T21:48:17Z

Include important definitions of terminology we use throughout the Snap project
Updates introduction on README.md to reflect clarification of terminology
Minor corrections to other docs

kindermoumoute · 2016-11-15T22:08:44Z

Could we clarify different configs in this glossary?

Global config: Snap daemon config.
Plugin config: config for a plugin.
Metric config: config for a metric.

kindermoumoute · 2016-11-15T22:47:55Z

And another one:

Global options: flags that are passed when executing snapd.

kjlyon · 2016-11-15T22:49:09Z

docs/GLOSSARY.md

@@ -0,0 +1,18 @@
+# Glossary
+Snap is simple in scope and it becomes simplier when you know the terminology we use throughout the project. Here they are: 


Spelling: 'simpler' or 'more simple' should be used

kjlyon · 2016-11-15T22:51:29Z

Looks good so far, I think it should be in alphabetical order though.

mbbroberg · 2016-11-15T22:51:46Z

Get 'em @kindermoumoute / @kjlyon. +1 to alphabetical. Going to fix that when we're done with comments.

kjlyon · 2016-11-15T23:12:27Z

We might want to add Slack on the list.

kjlyon · 2016-11-15T23:17:03Z

Should we also include some of the technologies we commonly reference like Travis CI or Docker, or do we assume people either know what those are or can google them?

candysmurf · 2016-11-15T23:26:53Z

docs/GLOSSARY.md

+* **Plugin Type: Publisher** - Persists metrics into a target endpoint
+* **Snap** -  The project name, focused on the Snap daemon and the plugins that power its collection, processing and publishing of telemetry
+* **Snap Telemetry** - The full name of the Snap project, used mostly for easy searching (like snap-telemetry.io) or hashtag (#SnapTelemetry)
+* **`snapctl`** - The command-line interface (CLI) for Snap, released as a [binary][binary]


do you like to use new term(snaptel...)?

I want the name change to happen in the same PR and not mix it up in this one. Anyone changing binary names will change this file via regex.

candysmurf · 2016-11-15T23:28:55Z

docs/GLOSSARY.md

+* **Config: Plugin Config** - key/value pairs stored in the `config` block within a Task Manifest ([example](https://github.com/intelsdi-x/snap-plugin-collector-meminfo/blob/master/examples/tasks/task-mem.json#L24))
+* **Metric Catalog** - List of all available metrics exposed by a running instance of the Snap daemon
+* **Plugin** - A [binary][binary] that is compatible with Snap by following the [Plugin Lifecycle](PLUGIN_LIFECYCLE.md)
+* **Plugin Type: Collector** - Uses sensors to gather data and present as a dynamically-generated namespaced catalog


do you need to say "uses sensors" here? catalog vs metrics?

I changed the language 👍

candysmurf · 2016-11-15T23:29:29Z

docs/GLOSSARY.md

+* **Snap** -  The project name, focused on the Snap daemon and the plugins that power its collection, processing and publishing of telemetry
+* **Snap Telemetry** - The full name of the Snap project, used mostly for easy searching (like snap-telemetry.io) or hashtag (#SnapTelemetry)
+* **`snapctl`** - The command-line interface (CLI) for Snap, released as a [binary][binary]
+* **`snapd`** - The [daemon process](http://www.linfo.org/daemon.html) for Snap, released as a [binary][binary]


Same as above

andrzej-k · 2016-11-16T08:09:23Z

docs/PLUGIN_AUTHORING.md

+
+Please include a `status: under-construction` or one of the other states mentioned above in your `metadata.yml` file. You can also embed the following images in the top of your README.md: 
+
+<< Rendered images as smaller than full size.


Hmm, seems that something is missing here...

andrzej-k · 2016-11-16T08:11:54Z

This is great work @mjbrender, especially introduction of plugin's maturity indicators.
Minor comment: How about adding following to the Glossary?

(Metric) Namespace,
Dynamic Metric,
Distributed Workflow,
Loading a Plugin,
Starting a Task

mbbroberg · 2016-11-16T21:52:22Z

Thanks @andrzej-k. Overall comment to your request is that we should definitely continue to explain what our language means. When it comes to actions (Loading a Plugin or Starting a Task), these should be explained in the advanced documentation for the given topic.

Specifically:

(Metric) Namespace, << adding
Dynamic Metric, << adding
Distributed Workflow, << adding
Loading a Plugin, << won't add - explained in PLUGIN_LIFECYCLE.md
Starting a Task << won't add - explained in TASKS.md

mbbroberg · 2016-11-16T23:41:19Z

@kjlyon external tools are assumed knowledge in this one. This list should help people navigate using Snap specifically.

kjlyon

This looks really great. I like the idea of adding a glossary. Though, the first time a term is mentioned in our documentation I think we should link them to our glossary definition of that word.

kjlyon · 2016-11-17T19:55:28Z

README.md

  * **Publishers** - Store telemetry into a wide array of systems. Snap decouples the collection of telemetry from the implementation of where to send it. Snap comes with a large library of publisher plugins that allow exposure to telemetry analytics systems both custom and common. This flexibility allows Snap to be valuable to open source and commercial ecosystems alike by writing a publisher for their architectures.

-
-* **Dynamic Updates**: Snap is designed to evolve. Each scheduled workflow automatically uses the most mature plugin for that step, unless the collection is pinned to a specific version (e.g. get /intel/psutil/load/load1/v1). Loading a new plugin automatically upgrades running workflows in tasks. Load plugins dynamically, without a restart to the service or server. This dynamically extends the metric catalog when loaded, giving access to new measurements immediately. Swapping a newer version plugin for an old one in a safe transaction. All of these behaviors allow for simple and secure bug fixes, security patching, and improving accuracy in production.
+* **Dynamic Updates**: Snap is designed to evolve. Each scheduled workflow automatically uses the most mature plugin for that step, unless the collection is pinned to a specific version (e.g. get `/intel/psutil/load/load1/v1`). Loading a new plugin automatically upgrades running workflows in tasks. Load plugins dynamically, without a restart to the service or server. This dynamically extends the metric catalog when loaded, giving access to new measurements immediately. Swapping a newer version plugin for an old one in a safe transaction. All of these behaviors allow for simple and secure bug fixes, security patching, and improving accuracy in production.

 * **Snap tribe**: Snap is designed for ease of administration. With Snap tribe, nodes work in groups (aka tribes). Requests are made through agreement- or task-based node groups, designed as a scalable gossip-based node-to-node communication process. Administrators can control all Snap nodes in a tribe agreement by messaging just one of them. There is auto-discovery of new nodes and import of tasks and plugins from nodes within a given tribe. It is cluster configuration management made simple.


Should Tribe be capitalized in this header and paragraph.

kjlyon · 2016-11-17T20:06:54Z

README.md


 ### Running Tasks

-To collect data, you need to create a [task](docs/TASKS.md) by loading a `Task Manifest`. The manifest contains a specification for what interval a set of metrics are gathered, how the data is transformed, and where the information is published. For more information see [task](docs/TASKS.md) documentation.
+To collect data, you need to create a task by loading a `Task Manifest`. The Task Manifest contains a specification for what interval a set of metrics are gathered, how the data is transformed, and where the information is published. For more information see [task](docs/TASKS.md) documentation.


When a word is referred to for the first time, like here 'Task Manifest' is being introduced for the first time, we should add a link to that entry in the glossary.

That feels redundant here - we describe a Task Manifest in this paragraph while the glossary is more a overall reference and doesn't need regular linking. We should link to deeper dive topics inside docs/.

kjlyon · 2016-11-17T20:11:42Z

README.md

@@ -316,28 +317,26 @@ We have a few known features we want to take on from here while we remain open f
 If you would like to propose a feature, please [open an Issue](https://github.com/intelsdi-x/snap/issues)) that includes RFC in it (for [request for comments](https://en.wikipedia.org/wiki/Request_for_Comments)).

 ## Community Support
-This repository is one of **many** projects in the **Snap framework**. Discuss your questions about Snap by reaching out to us:
-
-* Through GitHub Issues. Issues is our home for **all** needs: Q&A on everything - installation, request for events, integrations, bug issues, futures. [Open up an Issue](https://github.com/intelsdi-x/snap/issues) and know there's no wrong question for us.


Is this deleted information being said somewhere else in the documentation? I feel like it's important to invite others to contact us on github, slack or post a Snap blog. I can incorporate some of it into the Contact Us section of Maintainers.md. It may fit better there.

Good call - it's redundant to the information covered below in Contributing

kjlyon · 2016-11-17T20:14:36Z

README.md

-* _Feedback_: try it and tell us about it through issues, blog posts or Twitter
-* _Contributors_: We can always use more eyes on the core framework and its testing
+* _Contributors_: We always appreciate more eyes on the core framework and plugins
+* _Feedback_: try it and tell us about it on [our Slack team](https://intelsdi-x.herokuapp.com/), through a blog posts or Twitter with #SnapTelemetry


Change 'our Slack team' to just 'Slack' or reword for clarity. Here are we offering users to post a blog to our Medium.com publication? This might be a good place for that link.

Leaving "our" to separate it from the many other Slack teams out there. We can hash this out in more detail another time. Added link for blog.

kjlyon · 2016-11-17T20:19:12Z

docs/GLOSSARY.md

+* A workflow where one or more steps have a remote target specified ([reference](https://github.com/intelsdi-x/snap/blob/master/docs/DISTRIBUTED_WORKFLOW_ARCHITECTURE.md))
+
+### Workflow Manifest 
+* A file that describes only the workflow of a Task ([example at the bottom](https://github.com/intelsdi-x/snap/blob/master/docs/SNAPCTL.md))


Can you fix this link to take you to the bottom of the document when clicked.

👍 . Reminder to @nanliu or whomever does the name edits, we will need to replace the URL in this document as well (with the same capitalization).

kjlyon · 2016-11-17T20:22:04Z

README.md

-[![Join the chat on Slack](https://intelsdi-x.herokuapp.com/badge.svg)](https://intelsdi-x.herokuapp.com/)
-[![Build Status](https://travis-ci.org/intelsdi-x/snap.svg?branch=master)](https://travis-ci.org/intelsdi-x/snap)
-[![Go Report Card](https://goreportcard.com/badge/intelsdi-x/snap)](https://goreportcard.com/report/intelsdi-x/snap)
+**Snap** is an open telemetry framework designed to simplify the collection, processing and publishing of system data through a single API. The goals of this project are to:


I liked the feel of the previous README header. It was very simple and clean. Maybe try putting these words under the Snappy picture and see how that looks.

kjlyon · 2016-11-17T20:23:13Z

README.md


+<img src="https://cloud.githubusercontent.com/assets/1744971/20331694/e07e9148-ab5b-11e6-856a-e4e956540077.png" width="70%">


Did you mean to change the Snappy picture?

Yes - changed the URL at the bottom of the image.

kjlyon · 2016-11-17T20:56:44Z

README.md

-* Through GitHub Issues. Issues is our home for **all** needs: Q&A on everything - installation, request for events, integrations, bug issues, futures. [Open up an Issue](https://github.com/intelsdi-x/snap/issues) and know there's no wrong question for us.
-* We also have a [Slack team](https://intelsdi-x.herokuapp.com/) where we hang out
-* Submit a blog post on your use of Snap to [our Medium.com publication](https://medium.com/intel-sdi)
+This repository is one of many in the Snap framework and [has maintainers supporting it](docs/MAINTAINERS.md). We love contribution from our community along the way. No improvement is too small.


contribution should be plural.

kindermoumoute · 2016-11-18T01:22:38Z

docs/GLOSSARY.md

+    * [Workflow Manifest](#workflow-manifest) 
+
+### Config: Global Config 
+* Values loaded at runtime of the daemon ([reference](https://github.com/intelsdi-x/snap/blob/master/docs/SNAPD_CONFIGURATION.md))


I really like the idea to link to an actual context! 👍

Can you use a relative path for url so links work from other branch/fork?
e.g.

([reference](SNAPD_CONFIGURATION.md))

Good catch - I updated them all and rebased. Could you verify @kindermoumoute? Thanks!

@jcooklin

* Include terminology we use throughout the Snap project * Differentiation between snap daemon and plugin maturity * Minor edits to how markdown files talk about plugins * Wordsmithed glossary of terms with @jcooklin. It gets deep * Cleaned up some verbiage in other docs 🍬

kjlyon · 2016-11-18T21:30:05Z

👍 LGTM

kjlyon · 2016-11-18T22:22:54Z

README.md


-The full project lives here, at http://github.com/intelsdi-x/snap.
+This note is especially important for plugins. While the Snap framework is hardened through tons of use, **plugins mature at their own pace**. If you have subject matter expertise related to a plugin, please share your feedback on that repository. 


mbbroberg added the wip-do-not-merge label Nov 15, 2016

kjlyon reviewed Nov 15, 2016

View reviewed changes

candysmurf reviewed Nov 15, 2016

View reviewed changes

andrzej-k reviewed Nov 16, 2016

View reviewed changes

mbbroberg removed the wip-do-not-merge label Nov 17, 2016

kjlyon reviewed Nov 17, 2016

View reviewed changes

kindermoumoute reviewed Nov 18, 2016

View reviewed changes

kjlyon reviewed Nov 18, 2016

View reviewed changes

mbbroberg merged commit 9e94389 into intelsdi-x:master Nov 18, 2016

mbbroberg deleted the glossary branch November 18, 2016 22:31

		@@ -0,0 +1,18 @@
		# Glossary
		Snap is simple in scope and it becomes simplier when you know the terminology we use throughout the project. Here they are:


		Please include a `status: under-construction` or one of the other states mentioned above in your `metadata.yml` file. You can also embed the following images in the top of your README.md:

		<< Rendered images as smaller than full size.


		<img src="https://cloud.githubusercontent.com/assets/1744971/20331694/e07e9148-ab5b-11e6-856a-e4e956540077.png" width="70%">


		The full project lives here, at http://github.com/intelsdi-x/snap.
		This note is especially important for plugins. While the Snap framework is hardened through tons of use, plugins mature at their own pace. If you have subject matter expertise related to a plugin, please share your feedback on that repository.

Designing glossary of terms #1352

Designing glossary of terms #1352

Conversation

mbbroberg commented Nov 15, 2016

kindermoumoute commented Nov 15, 2016

kindermoumoute commented Nov 15, 2016

Choose a reason for hiding this comment

kjlyon commented Nov 15, 2016

mbbroberg commented Nov 15, 2016

kjlyon commented Nov 15, 2016

kjlyon commented Nov 15, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

andrzej-k commented Nov 16, 2016

mbbroberg commented Nov 16, 2016 • edited Loading

mbbroberg commented Nov 16, 2016

kjlyon left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kindermoumoute Nov 18, 2016 • edited Loading

Choose a reason for hiding this comment

mbbroberg Nov 18, 2016 • edited Loading

Choose a reason for hiding this comment

kjlyon commented Nov 18, 2016

Choose a reason for hiding this comment

mbbroberg commented Nov 16, 2016 •

edited

Loading

kindermoumoute Nov 18, 2016 •

edited

Loading

mbbroberg Nov 18, 2016 •

edited

Loading