docs

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ## Next
 - `Update-AuPackage`
-  - New feature **strams** that extends `au_GetLatest` with option to return multiple HashTables (one for each stream).
+  - New feature [strams](https://github.com/majkinetor/au#streams) that extends `au_GetLatest` with option to return multiple HashTables (one for each stream).
   - New parameter `IncludeStream` to force update of spcecific stream.
 - `au_BeforeUpdate` and `au_AfterUpdate` now provide parameter `Package` of type `[AUPackage]` which you can use to modify Nuspec data.
 - Added new function `Set-DescriptionFromReadme` that is called automatically when README.md is present in the package folder ([#85](https://github.com/majkinetor/au/issues/85)). See [documentation](README.md#automatic-package-description-from-readmemd).

README.md

@@ -63,21 +63,26 @@ function global:au_GetLatest {
 
 The returned version is later compared to the one in the nuspec file and if remote version is higher, the files will be updated. The returned keys of this HashTable are available via global variable `$global:Latest` (along with some keys that AU generates). You can put whatever data you need in the returned HashTable - this data can be used later in `au_SearchReplace`.
 
-
 #### Streams
 
-When multiple streams have to be handled, multiple HashTables can be put together in order to describe each supported stream.
+The software vendor may maintain _multiple latest versions_, of specific releases because of the need for long time support. `au_GetLatest` provies an option to return multiple HashTables in order for its user to monitor each supported software _stream_. Prior to streams, each stream was typically treated as a separate package and maintained independently. Using AU streams allows a single package updater to update multiple version streams in a single run:
 
 ```powershell
 function global:au_GetLatest {
      # ...
      $streams = @{}
-     $streams.'1.2' = @{ Version = $version12; URL32 = $url12 }
-     $streams.'1.3' = @{ Version = $version13; URL32 = $url13 }
+     $streams.'1.2' = @{ Version = $version12; URL32 = $url12 }  # $version12 = '1.2.3.1'
+     $streams.'1.3' = @{ Version = $version13; URL32 = $url13 }  # $version13 = '1.3.9'
      @{ Streams = $streams }
 }
 ```
 
+Latest stream versions are kept in the `<package_name>.json` file in the package directory.
+
+Take a look at few working stream examples to gain more understading:
+- [LibreOffice](https://github.com/chocolatey/chocolatey-coreteampackages/blob/master/automatic/libreoffice/update.ps1) package uses streams to manage two different variants of the software (prior to streams this was handled via 2 packages.)
+- [Python3](https://github.com/chocolatey/chocolatey-coreteampackages/blob/master/automatic/python3/update.ps1) package automatically finds available python 3 streams and keeps them up to date. 
+
 In order to help working with versions, function `Get-Version` can be called in order to parse [semver](http://semver.org/) versions in a flexible manner. It returns an `AUVersion` object with all the details about the version. Furthermore, this object can be compared and sorted.
 
 ```powershell