User/anramanath/documentation (#189)

anramanath · web-flow · commit 86ebf45b7706 · 2022-02-03T08:21:25.000-08:00
* init

* Overview

* Architecture.

* WIP Moving about information

* remove about info.

* fixes in links.

* tweak links.

* bullet list.

* Optional note.

* Comments + gerund.
diff --git a/documentation/Architecture/Overview.md b/documentation/Architecture/Overview.md
@@ -7,7 +7,7 @@ For more detailed information on how to create your own project using the SDK, p
 
 ## High-Level Interfaces
 
-The Microsoft Performance Toolkit SDK was built to empower users to analyze arbitrary data source (such as `.etl` files, `.ctf` files, SQL server logs, etc). 
+The Microsoft Performance Toolkit SDK was built to empower users to analyze arbitrary data sources (e.g. `.etl` files, `.ctf` files, SQL server logs, `.csv` files, etc.). 
 Users can develop extensible *SDK plugins* that contain logic for processing data sources into tables, which are sent to the *SDK driver* (such as 
 the [Windows Performance Analyzer](https://docs.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer)) to render. At the highest 
 level, it exposes the following interfaces:
@@ -17,20 +17,20 @@ level, it exposes the following interfaces:
 
 The interfaces depicted in this diagram are
 
-1) The SDK takes as input *data sources*, such as file paths, from the *SDK driver*. The SDK may receive this input when, for example, the user asks 
+1) The SDK receives *data sources* (e.g. file paths) from the *SDK driver*. For example, the SDK may receive this input when the user asks 
 the driver to open a file.
 2) The SDK passes the data sources to all *SDK plugins* which can support them. Plugins are 
 loaded dynamically at runtime by the SDK driver before the data sources are given to the SDK. In this example, 2 out of the 3 loaded plugins advertise that 
 they can handle the loaded data source.
 3) Plugins can optionally exchange data through *data cookers*, even if the two plugins do not have access to each others' source code. In this 
 example, plugin B queries for and receives data from plugin A. Note that this data can be programmatically 
-accessed by anyone - not just other plugins. See the Plugins section for more information.
+accessed by anyone - not just other plugins. See [Plugins](#Plugins) for more details.
 4) Each plugin given the data sources returns *tables* to the SDK. Note that a plugin which advertises support for a data source may return no tables, but that 
 is unlikely to happen in practice.
 5) The SDK outputs all tables created by plugins to the SDK driver.
-6) The SDK driver does whatever it wishes with the tables. For example, WPA displays the tables along with interactable and manipulable graphs.
+6) The SDK driver does whatever it wishes with the tables. For example, WPA displays the tables along with interactable and manipulatable graphs.
 
-Note that in this simplified example only *one* data source is given to the SDK. In practice, multiple data sources may be passed in simultatenously. The SDK 
+Note that in this example only *one* data source is given to the SDK. In practice, multiple data sources may be passed in simultatenously. The SDK 
 handles mapping data sources to the correct plugins, and each plugin sees as input a *list* of data sources for which it advertises support. 
 
 With these high-level interfaces defined, we will now examine each component in greater detail. 
@@ -44,9 +44,9 @@ more programmatic drivers such as scripts may pass down hard-coded data sources.
 
 We recommend using the [Windows Performance Analyzer](https://docs.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer) 
 as the SDK driver since it grants a plethora of tools for performance analysis. For more information on how to install WPA, 
-see [Using the SDK/Installing WPA](Using-the-SDK/Installing-WPA.md). 
+see [Using the SDK/Installing WPA](../Using-the-SDK/Installing-WPA.md). 
 
-Creating an SDK driver is currently outside the scope of this documentation, although it may be added in the future.
+Creating an SDK driver is currently outside the scope of this documentation.
 
 
 ## SDK
diff --git a/documentation/Architecture/The-Data-Processing-Pipeline.md b/documentation/Architecture/The-Data-Processing-Pipeline.md
@@ -56,10 +56,9 @@ From an interface perspective, a `DataCooker` has the following properties:
 * A `DataCooker` processes (cooks) this data
 * A `DataCooker` exposes zero or more __data output__ properties
 
-`DataOutput`s are the key component of data cookers, and are what achieve the last two goals outlined at the beginning of this document. 
-The SDK is aware of every `DataOutput` a given `DataCooker` advertises, and any assembly with access to an instance of 
-the SDK with a `DataCooker` loaded can query that cooker for any of its `DataOutput`s. For instance, a `Table` can 
-query transformed data outputted by a `DataCooker` defined inside its own assembly:
+`DataOutput`s are the key component to `DataCooker`s as they achieve the last two goals outlined at the beginning of this document. 
+The SDK is aware of every `DataOutput` a given `DataCooker` advertises. Any assembly the SDK loads concurrently with a `DataCooker` can query that cooker for any of its `DataOutput`s. 
+For instance, a `Table` can query transformed data outputted by a `DataCooker` defined inside its own assembly:
 
 <img src=".attachments/cooker_query.svg" width="800">
 
@@ -87,21 +86,21 @@ The SDK handles these cases differently, so it is important to understand the di
 
 #### Source Data Cookers
 
-A `SourceDataCooker` is a `DataCooker` which consumes data from a single `SourceParser`. It must specify
-1) The `SourceParser` to consume data from and
+A `SourceDataCooker` is a `DataCooker` which must specify
+1) A single `SourceParser` to consume data from
 2) The keys of the events it wishes to receive
 
 It is helpful to think of keys as "group names" here. A `SourceDataCooker` specifies the "groups," or "types," of 
 events it wishes to receive. 
 
-Finally, a `SourceDataCooker` will consume (cook) events *one at a time* as the `SourceParser` emits them
+Finally, a `SourceDataCooker` will consume (cook) events *one at a time* as the `SourceParser` emits them.
 
 #### Composite Data Cookers
 
 A `CompositeDataCooker` is a `DataCooker` which consumes data from one or more other `DataCooker`s. It must 
 specify all of the other `DataCookerPath`s for the `DataCooker`s which it depends upon. The SDK instructs
 the `CompositeDataCooker` when *all* of its dependencies have finished processing their data, at which point 
-the `CompositeDataCooker` can query the `DataOutput`s it needs to perform *its* transformations.
+the `CompositeDataCooker` can query the `DataOutput`s it needs to perform *its own* transformations.
 
 # Putting Everything Together
 
diff --git a/documentation/Glossary.md b/documentation/Glossary.md
@@ -32,7 +32,7 @@
 
 ## AboutInfo
 
-Exposes information about a plugin, such as its authors, copyright, and license. See [Adding About Information](./Using-the-SDK/Advanced/Adding-About-Information.md).
+Exposes information about a plugin, such as its authors, copyright, and license. See [Adding About Information](./Using-the-SDK/Creating-your-plugin.md#adding-about-information).
 
 ## Column
 
@@ -48,7 +48,8 @@ See also: [Projection](#projection).
 
 ## ColumnRole
 
-Meta-information about a [Column](#column) that defines the Column's role in data presentation. For example, a Column that contains a `Timestamp` whose value indicates when an event occured relative to the start of a [DataSource](#datasource) may be marked as a "start time" Column.
+Meta-information about a [Column](#column) that defines the Column's role in data presentation. 
+For example, a Column of `Timestamp` values relative to the start of a [DataSource](#datasource) may be marked as a "start time" Column.
 
 ## CompositeDataCooker
 
diff --git a/documentation/Overview.md b/documentation/Overview.md
@@ -1,6 +1,6 @@
 # Overview
 The Microsoft Performance Toolkit SDK allows developers to create "SDK plugins" that process and interpret data. 
-These plugins can be used by performance analysis applications that use the SDK runtime - such as [Windows Performance Analyzer](https://docs.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer) - to process data sources into structured, tabular data. Plugins may utilize the SDK's data-processing pipeline to both facilitate the creation of these tables and expose data that can be programmatically accessed by concurrently loaded plugins (even those without access to the originating plugin's source code).
+These plugins can be used by performance analysis applications that use the SDK runtime - such as [Windows Performance Analyzer](https://docs.microsoft.com/en-us/windows-hardware/test/wpt/windows-performance-analyzer) - to process data sources into structured, tabular data. Plugins may use the SDK's data-processing pipeline to both facilitate the creation of these tables and expose data that can be programmatically accessed by concurrently loaded plugins (even those without access to the originating plugin's source code).
 
 This folder contains instructions for developing SDK plugins and utilizing the SDK's various features.
 
diff --git a/documentation/Using-the-SDK/Advanced/Adding-About-Information.md b/documentation/Using-the-SDK/Advanced/Adding-About-Information.md
diff --git a/documentation/Using-the-SDK/Advanced/Overview.md b/documentation/Using-the-SDK/Advanced/Overview.md
@@ -2,6 +2,5 @@
 
 The following collection of documents outline more advanced usages of the SDK.
 
-- [Adding About Information](Adding-About-Information.md)
 - [Extending the SDK with your own implementations of `DataSource`](Creating-Your-Own-DataSource.md)
 - [Making your Extensions Disposable](Disposable-Extensions.md)
diff --git a/documentation/Using-the-SDK/Building-a-table.md b/documentation/Using-the-SDK/Building-a-table.md
@@ -1,11 +1,11 @@
 # Building a Table
 
-Table construction happens by interacting with an instance of an `ITableBuilder`. Broadly, `Tables` consist of 3 parts: columns, which are composed of `ColumnConfigurations` and `Projections`, and `TableConfigurations`. An `ITableBuilder` has methods that accept all three of these objects.
+Table construction happens by interacting with an instance of an `ITableBuilder`. Broadly, `Tables` consist of `TableConfigurations` and Columns. Columns can be further broken down into `ColumnConfigurations` and `Projections`. An `ITableBuilder` has methods to add both Columns and `TableConfigurations`.
 
 * [Column](#column)
   * [ColumnConfiguration](#columnconfiguration)
   * [Projection](#projection)
-* [Combining ColumnConfiguration and Projections](#combining-columnconfiguration-and-projections)
+  * [Combining ColumnConfiguration and Projections](#combining-columnconfiguration-and-projections)
 * [TableConfiguration](#tableconfiguration)
   * [ColumnRole](#columnrole)
 
@@ -45,7 +45,7 @@ public sealed class WordTable
 
 ### Projection
 
-A column's `Projection` is a function that maps a row index for a column to a piece of data. Projections are normally constructed at runtime by a `Build` method, since they depend on the data inside the final table. The SDK offers many helper methods for constructing `Projections`, such as
+A column's `Projection` is a function that maps a row index for a column to a piece of data. Projections are normally constructed at runtime by a `Build` method, since they depend on the data inside the final table. The SDK offers many helper methods for constructing `Projections`, such as:
 * `Projection.Index(IReadOnlyList<T> data)`, which projects a column index `i` to `data[i]`
 * `Projection.Compose(this IProjection<T1, T2>, Func<T2, TResult>)` which composes one `IProjection` with another method
 
@@ -58,7 +58,7 @@ var lineNumberProjection = baseProjection.Compose(lineItem => lineItem.LineNumbe
 var wordCountProjection = baseProjection.Compose(lineItem => lineItem.Words.Count());
 ```
 
-## Combining ColumnConfiguration and Projections
+### Combining ColumnConfiguration and Projections
 
 If we have the `ColumnConfigurations` and `Projections` above, we can add them to the table we're building by calling `ITableBuilder.AddColumn`:
 
@@ -102,7 +102,7 @@ tableBuilder.SetDefaultTableConfiguration(tableConfig);
 
 ### ColumnRole
 
-A `ColumnRole` is metadata information about a column that defines the column's role in data presentation. For example, a column that contains a `Timestamp` whose value indicates when an event occured relative to the start of a `DataSource`](#datasource)` may be marked as a "start time" Column:
+A `ColumnRole` is metadata information about a column that defines the column's role in data presentation. For example, a column of `Timestamp` values relative to the start of a `DataSource` may be marked as a "start time" Column:
 
 ```cs
 tableConfig.AddColumnRole(ColumnRole.StartTime, relativeTimestampColumnConfiguration);
diff --git a/documentation/Using-the-SDK/Creating-a-pipeline.md b/documentation/Using-the-SDK/Creating-a-pipeline.md
@@ -8,11 +8,11 @@ This document assumes you have already created a `ProcessingSource` and your plu
 
 The data-processing pipeline plugin framework is centered around a `SourceParser` and one-or-more `DataCookers`. The `CustomDataProcessor` your `ProcessingSource` creates delegates the task of parsing `DataSources` off to a `SourceParser`, who in turn emits __events__ that flow through `DataCookers`. In this framework, `Tables` are responsible for "building themselves" by querying `DataCookers` for their `DataOutputs`.
 
-This document is outlined into 4 distinct steps
-* [Creating a SourceParser](#creating-a-sourceparser)
-* [Creating a CustomDataProcessorWithSourceParser](#creating-a-customdataprocessorwithsourceparser)
-* [Linking Your CustomDataProcessor to Your ProcessingSource](#linking-your-customdataprocessor-to-your-processingsource)
-* [Creating a DataCooker](#creating-a-datacooker)
+There are 4 distinct steps in creating a Data-Processing Pipeline:
+1. [Creating a SourceParser](#creating-a-sourceparser)
+2. [Creating a CustomDataProcessorWithSourceParser](#creating-a-customdataprocessorwithsourceparser)
+3. [Linking Your CustomDataProcessor to Your ProcessingSource](#linking-your-customdataprocessor-to-your-processingsource)
+4. [Creating a DataCooker](#creating-a-datacooker)
 
 ## Creating a SourceParser
 
diff --git a/documentation/Using-the-SDK/Creating-a-simple-sdk-plugin.md b/documentation/Using-the-SDK/Creating-a-simple-sdk-plugin.md
@@ -12,11 +12,11 @@ In this framework, your `CustomDataProcessor` is responsible for
 
 > :information_source: When using the simple plugin framework, a `Table` is referred to as a `Simple Table`.
 
-This document is outlined into 4 distinct steps
-* [Creating a CustomDataProcessor](#creating-a-customdataprocessor)
-* [Creating a Simple Table](#creating-a-simple-table)
-* [Building Your Simple Table](#building-your-simple-table)
-* [Linking Your CustomDataProcessor to Your ProcessingSource](#linking-your-customdataprocessor-to-your-processingsource)
+There are 4 distinct steps in creating a Simple SDK Plugin:
+1. [Creating a CustomDataProcessor](#creating-a-customdataprocessor)
+2. [Creating a Simple Table](#creating-a-simple-table)
+3. [Building Your Simple Table](#building-your-simple-table)
+4. [Linking Your CustomDataProcessor to Your ProcessingSource](#linking-your-customdataprocessor-to-your-processingsource)
 
 ## Creating a CustomDataProcessor
 
diff --git a/documentation/Using-the-SDK/Creating-your-plugin.md b/documentation/Using-the-SDK/Creating-your-plugin.md
diff --git a/documentation/Using-the-SDK/Using-the-engine.md b/documentation/Using-the-SDK/Using-the-engine.md
