search

chocolatey / docs

https://docs.chocolatey.org - new docs website
Apache License 2.0
155 stars 175 forks source link

Narrative Docs / Walkthroughs #342

Open ferventcoder opened 7 years ago

ferventcoder commented 7 years ago

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

Troubleshooting

Installation

Package Repositories

Managing Software

Scripting

Integrations

Packaging Patterns

Community Package Repository

Advanced Scenarios

Contributing

ferventcoder commented 7 years ago

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

AdmiringWorm commented 7 years ago

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

ferventcoder commented 7 years ago

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 commented 7 years ago

@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:

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 commented 7 years ago

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. :+1:

ferventcoder commented 7 years ago

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 commented 7 years ago

cc @michaeltlombardi

ferventcoder commented 7 years ago

@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 commented 7 years ago

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.

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 commented 7 years ago

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

michaeltlombardi commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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.

Am I catching that aspect correctly?

DarwinJS commented 7 years ago

@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 commented 7 years ago

@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.

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 commented 7 years ago

@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 commented 7 years ago

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:

ferventcoder commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

Add a section about Chocolatey's PowerShell environment:

Other things as I think of them.

pauby commented 7 years ago

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

ferventcoder commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

@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 commented 7 years ago

From our conversations, my developer experience:

As for user experience:

bcurran3 commented 7 years ago

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 commented 7 years ago

Add comments here is good for now.

mwallner commented 7 years ago

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 commented 7 years ago

Packaging

ferventcoder commented 7 years ago

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

ferventcoder commented 7 years ago

General Setup/Use Tips

bcurran3 commented 7 years ago

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 commented 7 years ago

@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 commented 7 years ago

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 commented 7 years ago

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 commented 7 years ago

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

ferventcoder commented 7 years ago

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

ferventcoder commented 7 years ago

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

EntranceJew commented 7 years ago

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

ferventcoder commented 7 years ago

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

bcurran3 commented 7 years ago

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

elovelan commented 7 years ago

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 commented 7 years ago

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

ferventcoder commented 7 years ago

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

ferventcoder commented 6 years ago

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

gep13 commented 2 years ago

Moving this to the docs repository.