Narrative Docs / Walkthroughs

[ferventcoder]

We have a lot of great reference docs, which is good if you know exactly what you are looking for, but it would be good to also have more concept and narrative types of docs that are great for learning.

The below will become the docs home when complete. There are lots of needs for documentation and walkthroughs here though.

---

Getting Started

• What is Chocolatey? https://github.com/chocolatey/choco/wiki | https://github.com/chocolatey/choco/wiki/Why#what-is-chocolatey
• Why? https://github.com/chocolatey/choco/wiki/Why
• We already have x. What additional benefit does Chocolatey provide?
• How does it work?
• Security
• Terminology
• FAQs

Troubleshooting

• Troubleshooting
• I think I found a bug
• Support - open source
• Support - paid

Installation

• Planning your install
• Choosing your client(s)
• Installation
• Completely offline / internal
• Non-admin installation
• Setting up Chocolatey
• Setting up Chocolatey for organizational use
• Securing your Chocolatey installation
• Setting up Sources
• Proxies

Package Repositories

• Community Repository (the default) and Organizational Use
• What do I need to know?
• What are my options?
• Regular
• Proxy Repositories
• Aggregate Repositories

Managing Software

• Installing, Upgrading, and Uninstalling Software with Chocolatey
• Passing arguments to choco.exe
• Passing parameters to customize packages at runtime (package parameters and install arguments)
• Installing from a non-known source
• Installing Windows Features
• Alternative Sources - Installing Ruby Gems / Python / Cygwin and other sources
• Installing multiple versions of some software side by side
• What if the software I want to manage with Chocolatey is already installed?
• What commands can I call? (Command Reference)

Scripting

• Using choco.exe in scripts
• Using the Chocolatey.Lib API

Integrations

• Using Chocolatey with SCCM
• Using Chocolatey with MDT
• Using Chocolatey with PowerShell DSC
• Using Chocolatey with Puppet
• Using Chocolatey with Chef
• Using Chocolatey with Ansible
• Using Chocolatey with Salt
• Using Chocolatey with remote management tools (LabTech, RMM, Altiris, etc)

Packaging Patterns

• Creating Packages
• Packaging your own software
• Package Builder
• Embedding Binaries vs Download
  • Use of VERIFICATION.txt, LICENSE.txt and REDISTRIBUTION.pdf
• Installing an Installer
• Installing a Zip
• Zip + Installer
• Installing VSIX
• Installing PowerShell Modules
• Are there variables available for use?
• How can I take user input? and Ask the user for input (Read-Host and Prompt have timeouts Chocolatey's PowerShell)
• What functions are available? (PowerShell Function Reference)
• Creating Templates
• Internalizing an existing package (making offline w/no internet access)
• Pre-post checks
• Adding functionality to Chocolatey

Community Package Repository

• Maintaining packages
• Moderation
• Verifier failed
• Validator failed
• I'm getting comments/questions and not sure what is wrong

Advanced Scenarios

• Self-service - non-admins installing software
• Keeping secrets out of the logs
• Securing packages, even from your users

Contributing

• What do I need to know upfront?

• Guidelines

• Submitting Documentation

• PowerShell

• C#

• Other

• Versioning strategies for Chocolatey for less than v1 (SemVer compliance)

[ferventcoder]

@DarwinJS fyi, looking for ideas and input here. I know you have some packaging patterns

[AdmiringWorm]

For package patterns:
Maybe have something for installing vsix extensions, vscode extensions, browser extensions and powershell modules as well?

[ferventcoder]

Some (quite a bit of this is already available in the docs somewhere. The trick for quite a bit of it is providing it in a more user friendly way. The docs could use a good look over as well.

[DarwinJS]

@ferventcoder - how prescient of you. This week I completed about 80% of my next blog post "Testable Reference Pattern Manifesto (With a Working Example)"

In it I explain why I value this concept so much - it started with turning the CIS AWS Foundation Benchmark into a runnable script for creating an AWS account that is compliant with this security standard. No wait, actually it started with the reference specification I built for a custom PowerShell software delivery framework I built for deploying software under SCCM.

It has continued at work where I have made a Testable (or Working) Reference Pattern for the custom built configuration management system we use for orchestrating automation for AWS, Windows and Linux.

I personally believe that a set of testable patterns are way more valuable than pages of information attempting to explain the same exact thing.

I also believe that explanatory documentation should be done after working reference patterns and draw from them - then they end up being [a] more complete (because in building a WORKING pattern, the author forces themselves to bring all the necessary steps to mind) and the exact code they reference is [b] known to work, and [c] can be seen in action by the learner.

So if this effort were to adopt such an approach then "templates" should be able to be directly compiled and installed locally. (Perhaps with special functionality to block upload of reference patterns directly to chocolatey).

There are some possible challenges and creativity to be applied to make the concept work with Chocolatey, but I think the value to the first time chocolatey packager trying to step up to learn both the practical skills and best practices all at the same time is hard to over estimate.

Some possible adaptations to the idea to make it valuable to the Chocolatey packaging community:

• Perhaps not all templates should be working - but still enable and promote working patterns as the best way to teach. Maybe if a template includes a keyword like "workingpattern" - it would be known to behave in the ways described above.
• If some files need to stay the same so that their checksums match for future users of the pattern - rehost them on chocolatey (select ones that allow this).
• If some patterns need local binaries in the package - but it does not make sense to have a binary file transit inside the templates mechanism, make them downloadable or contained in another package.

I also think the current high level of commenting output by "choco new" (with code for stripping comments) is also a superior way to learn versus separately maintained documentation. Hopefully if working patterns were more targeted around specific scenarios, the comments could be cut back to the details of the scenario covered.

I feel the portion of the human mind dedicated to recognizing and adopting patterns is huge - the more "working" the patterns that fed in are - the higher the value. I think about how babies initially learn - purely by observing patterns - but more specifically "actual working patterns". (except when we interject to "teach" them using "incomplete pattern" methods that reflect our propensity to deconstructivism rather than the natural world's default of "holistic experiences")

Apologies for blathering - a topic I am passionate about - but more so recently. Some of this blather will probably make it into the article ;)

[ferventcoder]

This issue is a placeholder to gather walkthrough types of docs - the idea of "templates" and working through to a good working example is the same direction. 👍

[ferventcoder]

We do the heavy commenting and info in the generated choco new precisely because we believe it is high value and is meant to help folks fall into the pit of success. Our name for that is "just in time documentation" and "the right documentation, right when you need it."

[ferventcoder]

cc @michaeltlombardi

[ferventcoder]

@elovelan Managing Software - "Installing multiple versions of some software side by side" is the particular narrative / walkthrough with considerations, but it could also be approached from packaging patterns section as well.

[ferventcoder]

Packaging Patterns - Installing a Zip

[..snip..]

Where to Unpack

With installing a zip, explain Get-ToolsLocation and why Program Files is not the best idea.

Other Notes

Normally you would just let a zip unpack into the package directory (the $toolsDir variable seen in chocolateyInstall.ps1 after running choco new <pkgid>). This ensures that exe files are automatically shimmed and available to run immediately after the install.

However in some scenarios you may have other packages that will install components (like pkgid-someplugin) and want to maintain all of that outside of the packaging directories. Or for some other performance or pathing reason. In those cases we recommend installing to the Chocolatey Tools Location.

$unpackDirectory = Join-Path Get-ToolsLocation $packageName

By default Chocolatey Tools Location is c:\tools, but it can be whatever the user desires for it to be. We don't recommend attempting to access $env:ChocolateyToolsLocation directly as it may not be set yet or may be needing to be upgraded from another value (the validator on the community repo will also flag your package for required fixes if you do use that variable). That is all done when you call Get-ToolsLocation, so we recommend you simply call that function instead.

When you unpack outside of packaging directory, you need to manage ensuring any executables are on the PATH and available. This is already done automatically with exes that are in the package directory.

• For adding/updating PATH, see Install-ChocolateyPath
• For creating a shim from a location outside of the package, see Install-BinFile

Availability

Keep in mind with updating PATH that it does not take effect in the current process. Once choco.exe exits, that information is available and set in the registry, but you would need to close and reopen your command shell for it to "see" those changes. There is also refreshenv you can run from cmd.exe (you can also run it from powershell.exe if you have the Chocolatey PowerShell profile and tab completion installed). The trick is your users have to run this (and know to run this, choco does mention it if there are PATH updates during the install).

If you let Chocolatey create a shim or if you create a shim with Install-BinFile, that means the app will be available as soon as choco exits.

Unpacking to Custom Locations

If you want to use Package parameters and allow users to determine where that would be at runtime, use Install-ChocolateyZipPackage or Get-ChocolateyUnzip and in the uninstall script, you should call Uninstall-ChocolateyZipPackage as it will attempt to discover a file that contained where all of the unpacked files were placed so it can clean them up - just note that chocolatey/choco#1415 is a current issue.

[DarwinJS]

Recent blog on working reference patterns: https://cloudywindows.com/post/back-to-basics-testable-reference-pattern-manifesto-with-testable-sample-code/

[michaeltlombardi]

Coming in a bit late to the party, but looking down the list of narrative docs here, I see a mix of some concepts and some narrative. Chocolatey's reference docs are already pretty good.

The tone used in your snippet above, @ferventcoder, is a good one, especially for the concept of patterns.

RE: @DarwinJS's point of having testable reference patterns, using those patterns in narrative docs is an awesome way to onboard humans to a project. As I'm going down the road right now for thinking about how to bring chocolatey into my org the right way, I'm in a pretty good place to write some naive documentation and review other docs.

For organization of the docs, both the three-prong narrative/concept/reference works, as does a variation where you intersperse the narrative and concept docs and just make sure they're tagged somehow.

The important thing to keep in mind, I think, is that Chocolatey's documentation is a part of the UX and should be treated like it. Narrative docs help people walk right into the pit of success, especially when all of the reference patterns they see in the docs are good ones and anti-patterns are called out early, explicitly, and for clear reasons.

[ferventcoder]

The important thing to keep in mind, I think, is that Chocolatey's documentation is a part of the UX and should be treated like it. Narrative docs help people walk right into the pit of success, especially when all of the reference patterns they see in the docs are good ones and anti-patterns are called out early, explicitly, and for clear reasons.

Agreed on this aspect.

[ferventcoder]

For organization of the docs, both the three-prong narrative/concept/reference works, as does a variation where you intersperse the narrative and concept docs and just make sure they're tagged somehow.

I think I keep falling down on the difference between narrative and concept, would you be able to clarify that a bit @michaeltlombardi? Examples would be even better.

• Reference - information, like a dictionary laying out what is there.
• Concept - explanations of why, etc - like the packaging patterns section (https://github.com/chocolatey/choco/issues/1303#issuecomment-303804561)
• Narrative - walk throughs? Specifically walking someone through a task, possibly linking to concepts or reference (or intertwining concepts as specific call outs) - like https://chocolatey.org/docs/how-to-recompile-packages#how-to-internalizerecompile-an-existing-package-manually

Am I catching that aspect correctly?

[DarwinJS]

@ferventcoder - the Narrative example you give is good toward "a working reference pattern" because it uses an existing package as a starting point - so "working" by definition.

I wonder if a Narrative like "Installing an MSU" could be completely contained as comments - IF (big IF) the "working pattern" package stayed laser focused on "Installing an MSU" ?

Maybe if it needs to be web searchable, organizes a repo to be easily searchable or just publish "ChocolateyInstall.ps1" of the working reference pattern package to a web page?

Just trying to think if there is a way to reduce / eliminate documentation as separate web pages when it makes sense - won't always make sense.

[michaeltlombardi]

@ferventcoder - completely correct on reference, close on concept - concept also includes things like explanations of design decisions (especially if those decisions deviate from the obvious or standard choice), information around security, best practice, etc.

Narrative docs usually walk someone through something - you can write them as a "do this, then do this" walkthrough, but you can also write them as mini stories around concepts - the Phoenix Project is an example of narrative documentation around DevOps principles, for example.

Examples of good narrative docs also includes the learning materials for both puppet and chef where you interactively work your way through some synthetic problems, learning best practices as you go.

There's a couple other loose things that usually help with thinking about this.

• Reference is like an encyclopedia - pretty dry, very clear and direct. Prefer clarity and explicitness over just about everything else. For some languages you can autogenerate your markdown reference docs from your in-the-code reference docs (PlatyPS is an example of this).
• Concept docs are kinda like informal white papers - you explain not just what but why. Here the emphasis is still on clarity, but also on making sure to address questions that also pull the project off on tangents (for example, if you find yourself defending a design decision to people in issues more than once, you probably need a concept doc for that decision). Concept docs are for the project maintainers and the users both. A lot of the consumers of concept docs will be power users.
• Narrative docs are analogous to blog posts for the most part. The tone can be very informal because the goal is to quickly and safely get users or developers up to speed. Of the three types of docs, these are the closest to the people utilizing a project and so require the most safety and continual attention. Any code included in narrative docs must absolutely work without errors and where errors are probable be clearly and explicitly identified as well as including troubleshooting steps.

When I mentioned that there are two relatively good options, I meant:

1. We can split the documentation into three top level sections and organize by topic under that. For example:

└───docs
    ├───concept
    │   ├───community-repo
    │   ├───contributing
    │   ├───design
    │   ├───packaging
    │   └───security
    ├───narrative
    │   ├───getting-started
    │   ├───managing-software
    │   └───packaging
    └───reference

2. Alternatively, you can approach by topic instead of type (and then use either article tags or subfolders to distinguish between concept and narrative where necessary):

└───docs
    ├───community-repo
    ├───contributing
    ├───design
    ├───getting-started
    ├───managing-software
    ├───packaging
    ├───reference
    └───security

Option 2 is probably the saner one for the scope of the project - the first option is what I normally recommend for small projects which do a few things and have limited concerns around them. Most libraries/modules/etc are better with the first option than the second.

[michaeltlombardi]

@DarwinJS: Where possible, deduping effort on documentation is a good thing. I think that this is largely going to be a case of reference pattern and narrative documentation unless we're also going to inject the why's and notices into the reference pattern.

My concern with doing that is that there is a large portion of the user base who will never see the reference patterns as an option for learning - they'll go looking for narrative docs, not find them, and give up because it wasn't obvious.

Another portion of the user base will balk at having to learn by reading existing code that isn't dealt out slowly with explanations. They'll see the big block of code and be overloaded - even if the narrative doc literally uses all the same code over the course of it. Presentation can matter.

I'm not arguing that we shouldn't focus on reference patterns - they will definitely help us to write narrative and concept docs, and be useful in and of themselves - just that we'll probably have to do a bit of both.

[michaeltlombardi]

I think we should limit the scope for now to written documentation and reference patterns, but just like there are multiple types of docs there are many different useful formats - and people tend to learn best when given a multitude of formats. A non-exclusive sample of formats:

• Email documentation (narrative or concept, usually)
• Video tutorials (concept or narrative, usually narrative)
• Webinars
• Published web pages
• Published books (digital or print)
• Visual aids (workflows, charts, printouts)
• Interactive demos
• Gamified narrative docs
• MeetUps (two-way documentation - you push information about the project to people and find out the pain points in your existing docs)
• Podcasting / Audiobooks (Usually narrative or concept, again)

[ferventcoder]

I wonder if a Narrative like "Installing an MSU" could be completely contained as comments - IF (big IF) the "working pattern" package stayed laser focused on "Installing an MSU" ?

@DarwinJS @michaeltlombardi We can also set out to create an MSU template that is laser focused on creating a package for an MSU. We have one for an MSI now. https://chocolatey.org/packages/msi.template. The templates make great reference patterns (by the way @DarwinJS, I'm still waiting for you to create some of these template packages * hint, hint *).

[ferventcoder]

To me great reference patterns are the templates - they get you things you need, and provide just enough documentation to get you going and set up correctly. They don't immediately work, but they help the user move to getting a working package.

[ferventcoder]

Add a section about Chocolatey's PowerShell environment:

• Always runs PowerShell in .NET 4.x, even if PowerShell v2. The only exception is if you add --use-system-powershell (but that won't work in choco licensed environments). This can also run into Mixed mode environment issues if you are running a DLL that expects to be in .NET 2.0 (like the BITS module).
• Anything that would normally block in PowerShell (e.g. Read-Host, Prompt, etc) will have a 30 second timeout in Chocolatey's PowerShell environment when run with -y. Choose a good default answer for unattended deployments.
• Chocolatey runs PowerShell with Debug and Verbose on so it can log the info to a file, but it manages whether that shows on screen based on user options.

Other things as I think of them.

[pauby]

Add a section about packaging (or more specifically the pack command), versions and variables within the nuspec.

[ferventcoder]

Section on shimgens and how they work, how to add them to the packaging for unzipped or downloaded resources. Reference: May 29, 2017 9:42 AM

[DarwinJS]

Here is one that handles installing "Removed" Windows features - I believe since I've done this I came across one more registry key that would be helpful to add. This particular pattern addresses the "20" part of the 80/20 rule of when installing a "removed" windows feature just WILL NOT work.
https://github.com/DarwinJS/ChocolateyDesignPatterns/tree/master/UniversalDotNet3.5

[DarwinJS]

For MSUs the best thing I have come up with is code the figures out when you've had an error and then pulls any errors from the MSU log (that you of course have had to create during install). Another one I can think of is detecting remote execution of .MSUs - which won't work - and giving a more appropriate error.

I wish I had more time to work these up myself - but I don't - I am happy to share the snippets.

[DarwinJS]

@michaeltlombardi - in address to your concerns about code only (which I see as valid) I meant to give room for that by: [a] also publish the code in a webpage in a wiki designed to teach how to and/or [b] augment a working, commented pattern with a complete how to if it is justified.

My main point is to [a] start with working code and [b] manage any such examples with on ongoing insistence that the code be tested and working. (Automated QA from CI).

@ferventcoder - It may be possible merge the concepts of "Chocolatey template" with "working reference pattern" by having templates have the option (not requirement) of [a] including "makethisintoaworkingpackage.ps1" which gathers and places resources and possibly retokenizes the code (maybe "choco new templatename -workingpattern" could call this special subscript) and [b] tagging it as a "working reference pattern" in the repo so that people looking to learn could identify the subset of templates that have this "working reference pattern" functionality and [c] if you believe in the concept enough, require any templates that are considered officially published by "chocolatey.org" to have the "working reference pattern" characteristics identified above.
This idea essentially makes "working reference patterns" an [a] optional, [b] superset of "chocolate templates"

[EntranceJew]

From our conversations, my developer experience:

• All the docs point toward using the thing that isn't AU, in terms of having the most pictures and resources, even the template repo makes a bigger emphasis on how to set up the not-AU folder so it appears more thorough
• Pictures. They make things less scary, they give people following along a way to say "hey, that's what I have, I guess I'm doing alright!". The docs are also very dense and in some cases too much text appears on a single page. Sometimes a picture or a text representation of a console interaction says more than the text that describes it. Or it gives the user a way to look at something, identify its purpose, and move ahead without reading as much.
• The site's lack of expandable categories in the doc titles frequently mean grazing past all the sell-you-on-it text and straining to parse the auto-generated docs or typically very light direction. There's no full ride-along way to author a package the same way there is for the ketarin templates, which has the drawing power to make someone use something depreciated because the recommended way leaves you with no clear entry point. Right now, if you linked me to the AU docs I wouldn't even understand how to use the functions it provides, because I wouldn't understand how powershell functions play a part in making a package to put on the site.
• I had to learn powershell for all this and that's been a bit of a ride so it wasn't the easiest to really know what to do. Documents regarding basic syntax, best practices, and control flow would help users acquire what they need from a site to include into a script. I have programmed before, but powershell (in my limited experience) either something that people ignore completely or they're fully immersed in due to MS platform / development. I fell into the former category.
• How do we get started with vscode for powershell scripts? How do I get autocomplete for chocolatey functions in my vscode profile? If ISE is so bad, is there any way to make it usable?
• We could use more docs on getting certain text from xpaths via Invoke-WebRequest, or even helpers. A once-through with features like this and the many use cases for it would help a lot, especially since I had to exclude the simple flag and get down and dirty with ParsedHtml more than once.
• The ability to parse page markup into markdown would be invaluable to populating release notes.
• If the default chocolatey methods don't work, I end up not knowing what exactly the default chocolatey methods do and have to work really hard to replicate what they do and I don't feel like I have a complete mental list of what gets done.
• Although the nuspec docs are complete, the pattern globbing it uses is hard to understand. The fact that you can't have multiple directives and manually specify a single file, you need to have one directive and you separate file globs with ;, which doesn't stand out without a lot of examples.
• We need a document with a case-by-case situations for which repository is the best example of how to handle common problems, such as:
  • When you need to get the version from a webpage manually, in order to guess the download URL.
  • When the install process is not totally silent, ways to extract the files and treat it like it is an un-elevated install.
  • When the portable install requires elevated chocolatey commands, how to recreate them.
  • How to make a meta/install/portable trio install without duplicating nuspec info or having the update script obtain it for you.
  • Use cases and how-to write a beforeUpdate script. How to identify when this is necessary and how to test for it.
• A lot of examples go through getting the version from the first page exe, optimistically, doesn't teach how to manually extract the version using ParsedHtml, getElementsByTagName, ChildNodes, or regexes https://regex101.com/
• Default template isn't https://github.com/majkinetor/au-packages/tree/master/_template, as it should probably be, with some fixings for generating the template per-user or better replacing some strings.
• Should old versions of packages be expected to serve old versions of software? Should the 0.17.3 package version always get that package? What if the install script always gets "latest.msi"? Should maintainers test and download historic package versions? If not, why even list them if the hashes / procedure will surely not match? Do these old versions get tested and invalidated?
• Are there a common set of parameters that should be expected to work on packages? How should package maintainers be expected to implement these? (e.g. install paths) Is there a common dialect for passing these parameters through?
• General best practices are hard to ascertain, because the documents specify the bare minimum a package should be but never top-down what the ideal, gold-star package SHOULD be. From here, a document should be designed on how to obtain this and what to do if the software vendor's site complicates providing this. Existing packages should be reviewed and scored on this sort of standard. We could use best practices for:
  • Where do files get downloaded to?
  • Where's the best place to extract them from and to?
  • Where do I manually install files to, should the need arise?
  • What is the best source of the software? When might we use an alternative source?
  • How do I acquire as much info dynamically as possible?
  • What should I do about start menu / desktop icons?
  • What are the moderation standards, and when do they apply?
• Could any of the above questions be formed into an interactive template script, by forming the guideliens into an interactive checklist or flow chart to make handling them less subjective and find some commonality between them all?
• The top of the docs has a package builder, which sounds like a thousand times more convenient than anything else I've gone through here. Although the package builder doesn't fit the bill of the interactive template script, it's something that I immediately reached for after only sort of understanding choco new.

As for user experience:

• When I did my initial shopping list things felt pretty complete but then when packages started to fail I was a little confused about what the checksum deal was about, something I wouldn't really know about if I didn't know how the internals worked and seeing the difference between AU and the old way firsthand.
• There are a lot of packages that are too old to have been verified, and were grandfathered in. After manually downloading some of these packages or viewing their page and source it was easy to determine that the scripts were not being updated. Some of these packages have been claimed by a moderator but have gone without final approval for up to months.

[bcurran3]

Where should any submissions take place?

I would love to supply some packaging templates along with explanations and scenarios, but I don't want to write the 10 pages before and after!

[ferventcoder]

Add comments here is good for now.

[mwallner]

This might go under "Setting up Chocolatey for organizational use" : http://mwallner.net/2017/06/10/using-chocolatey-in-corporate-environments-part-1/ - even though just "part 1" :-)

[ferventcoder]

Packaging

• Adding files in folders that are not the default tools folder and how to ensure in the nuspec that they get packed in
• Avoid renaming the nupkg files that are produced.
• Use only choco pack to package files. Attempting to do this yourself may not produce files Chocolatey or NuGet can understand as there are additional files created.

[ferventcoder]

Discuss issues with attempting to use a singular network cache for multiple machines.

• "choco upgrade chocolatey" fails choco#970
• https://groups.google.com/d/msgid/chocolatey/ddda4c98-ba5a-4eee-beb7-8ff331fbab9b%40googlegroups.com

[ferventcoder]

General Setup/Use Tips

• Do not manage the configuration file as a whole yourself. Use providers or directly with choco commands (choco config, choco feature, choco source, choco apikey, etc).
• Do not use your own commands to push or place packages on repositories. This could produce incompatibilities when Chocolatey is attempting to install. Simply use choco push and let Chocolatey work with the remote package repository to set those files correctly.

[bcurran3]

I would like to help out in some way on the topic of packaging.

Is the documentation available for pull requests to submit changes?

I tried to look into this a few weeks ago and suggesting changes to the documentation seems difficult due to the current way the information is presented (spread out all over the place). I'm sure from the Chocolatey Team's point of view it's logical and familiar as it's probably referred to frequently, but for the rest of us it can be a real chore trying to find specific info at times.

I basically made the decision that I'm going to create "Packaging 101 BCurran3's Way" of some sort. It's in my head frequently but life is busy right now and making money to pay the mortgage and put food on the table takes priority over volunteer work. Eventually I'll get it done. I consider it a race between whatever side blog I create versus the official documentation update. Whenever I get it done, anything I post is up for grabs in official documentation if deemed useful. In the meantime I'm still curious if there is any easy way to edit existing documentation instead of just posting it here. (All the link jumps would be a real bitch to post in the forum.)

[elovelan]

@ferventcoder, comments are a tough way to do this, can we use a temporary repo or branch instead? PRs would allow discussion of individual topics as well as allowing multiple contributions to a single topic.

A branch might be best since it can be turned into a PR into the main repo once it's "ready"

[DarwinJS]

powershell.org uses both gitbook.com and leanpub.com for publishing book like content. I'm not sure, but there might be value in understanding if you can make sure that the establishment of this learning content in a repo is compatible with one or both of these sites.

So this repo: http://github.com/devops-collective-inc

Becomes these books:
https://www.gitbook.com/@devops-collective-inc
https://leanpub.com/u/devopscollective

[michaeltlombardi]

Strongly recommend gitbook for documentation; strongly enough to be working on a scaffolding/ease-of-use PowerShell module for it.

GitBook is relatively straightforward to implement and use, helps keep docs with code, and is endlessly extensible (for situations where you need that extensibility).

[ferventcoder]

@elovelan the repo is at https://github.com/chocolatey/choco-wiki.

[ferventcoder]

Gitbook looks awesome!! Why am I just now learning of this?

[ferventcoder]

Let's do this instead, collaborate here - https://github.com/chocolatey/chocolatey-book

[EntranceJew]

@ferventcoder is there supposed to be something there? I can't even irony fork it to contribute.

[ferventcoder]

@EntranceJew I probably should have been a little more clear - I just created this repository as a place we can collaborate.

[bcurran3]

I'm not much further along.
https://github.com/bcurran3/ChocolateyPackages/wiki
Hopefully I can cross-pollinate later.

[elovelan]

I've created https://github.com/elovelan/chocolatey-book (basically just gitbook init) if you need a starting point for that repo @ferventcoder. We can't open PRs against an empty repo.

[ferventcoder]

@elovelan ah, didn't know that. Let me get something up there.

[ferventcoder]

@elovelan I have a .gitignore up. Feel free to send a PR now. Thanks!

[ferventcoder]

Packaging and CI/CD: https://gitter.im/chocolatey/chocolatey.org?at=5a623227e0141226506758b3

[gep13]

Moving this to the docs repository.