Needs better documentation

[Tiberriver256]

Hey guys,

I wanted to contribute to the documentation for the project because I think this is an awesome project but the lack of solid documentation is making it a bit difficult to pick up on usage.

I just wanted to start a conversation about what would be ideal as far as documentation goes. It seems right now we have:

1. General overview in ReadMe.md at the root
2. Various examples in the examples folder

Should we consider moving these sections to the Wiki to allow better structuring and navigation moving forward? The documentation for this particular project could and should become fairly large the more that is covered in IIS.

[tysonjhayes]

So I like the idea here and I totally want to support in getting better documentation in general. Could you give me an idea of what you are looking to cover here vs what we would find in PowerShell/PowerShell-docs?

[Tiberriver256]

Nothing crazy different from what you have now. Just structured out with links to make it a bit easier to navigate.

i was thinking something close to the msdn documentation for production DSC Resources (Example: FileResource) would also benefit for each of the resources. Having the syntax, properties and an example instead of just the properties would be great.

Maybe outlined something like:

Overview

Resources

xResource

Syntax

Properties

Example

xResource2

Syntax

Properties

Examples

FAQ

WebAdministration vs xWebAdministration vs cWebAdministration

How do I contribute?

The future of xWebAdministration

Others??

Examples

Registering PHP

Stopping the default website

Create a new website

Creating the default website using configuration data

All resources (end-to-end scenario)

Community Blog / Examples (List of blog postings regarding the project)

[tysonjhayes]

Seems pretty good. Why are you interested in using the wiki instead of a collection of markdown files? The markdown files may allow us to use similar build processes and publishing steps as the powershell docs script (ultimately allowing us to publish on msdn would be my goal here). Just kind of thinking out loud here, so grain of salt here. Is the wiki just giving a better structure? Could we rejigger the readme.md to point to these files?

running through this quickly as my battery is dying, I'll try to give this more thought overnight and get back to you.

[Tiberriver256]

This is the magic of the wiki. It is a git repo of just MD files.

https://help.github.com/articles/adding-and-editing-wiki-pages-locally/

It is just the standard location for storing your collection of MD files I think.

[PlagueHO]

Might be worth looking at how the xSharePoint resource does it. I seem to recall that @BrianFarnhill mentioned something about how they have an automated process to build the wiki content from the Resource MOFs. Might be worth adopting the practice that repo is using?

[BrianFarnhill]

Yea we do some stuff automatically at this point - here's the quick run down:

1. Comments to the schema.mof file for description and examples
2. Description property used on all properties in schema.mof file
3. Custom PS script grabs all of this and generates:
   • Custom help for the PowerShell module as "about_xSPResourceName"
   • Wiki pages that I then commit in to the wiki repo

An example of the documentation is on xSPCreateFarm.schema.mof

An example of the generated help in the PS module can come from what's in the latest dev feed

Lastly an example of the wiki documentation is also available for xSPCreateFarm

This allows us a few benefits:

• I can code review the documentation at the same time as the pull request that comes in
• We have consistent documentation on the wiki and in the module itself
• We don't need to write the doco for the parameters table as that gets generated from the schema itself, meaning we write less doco manually

Happy to discuss it in more detail if anyone is interested

[tysonjhayes]

Could you share the PS Script that does this automagic? This seems pretty awesome.

[Tiberriver256]

@BrianFarnhill -- drool

That sounds great. All I would be doing then is creating examples, reviewing the script output and enjoying the power of the xWebAdministration module.

[BrianFarnhill]

@Tiberriver256 Glad you like the sound of it :)

@tysonjhayes There are a couple of scripts you need to look at:

• First is the cript that parses the MOF files - check out the Get-MofSchemaObject function in my Test helpers module to see how we read the MOF files in to manageable objects in scripts. This could be a little more robust (I know it gets a little touchy about casing and spacing in some scenarios right now, haven't had time to touch it up though)
• Next the script to generate the wiki pages will be used to spit out the markdown files based on the data we collected about the MOF files
• Lastly the script to generate the PS help files will generate the help files for the module. We actually integrate this in to the AppVeyor build process as well so that every build has the doco that is correct for the schemas in that build

[PlagueHO]

Might I suggest that we see if we can integrate some of this process into the DSCResource repo? It seems like it might be pretty useful to many of the other resource modules that are starting to get pretty big (e.g. xActiveDirectory).

[BrianFarnhill]

Worth discussing - @tysonjhayes can you ping me an email internally (look me up in the GAL) with the other relevant people/usual suspects cc'ed and we can get some agreement and set standards on this sort of stuff going forward?

[tysonjhayes]

Sorry for the delay here I'll try to send out some communication today.

[PlagueHO]

@BrianFarnhill - anything I can help with to get this stuff into the DSCResource core? There is some work being done on this at the moment and if we can at least get some templates in place it'll get things moving. I'm happy to help out if I can.

[BrianFarnhill]

I was just sending @tysonjhayes an email about this - just wanted to make sure we all get on the same page in terms of how all the modules can use this first, then we can move forward on it. I'm more than happy to split the code out and show it in to the core DSCResource bit though

[Tiberriver256]

Just checking back in. Let me know when you guys come to a consensus and I'll lend a hand where I can.

[BrianFarnhill]

Hey @Tiberriver256 - so I've been rolling around some changes I wanna make to the xSharePoint resource's approach to documentation generation before we try to look at how we can make it a more widespread thing (I captured an issue for it in my repo this morning). I want to better structure my examples to be 'per resource' rather than just in the comments of the MOF file like they are now so they can be a source of official examples as well as documentation too. From there the only comments in the MOF are the description, which I think there has to be a better place to put it than in the MOF file itself (yes its valid but its not obvious - it just solved the need for us to make sure we got the documentation in at the same time as the PR). So once we tackle that and aren't depending on filling the MOF's with comments for this, that's the point that I think we take this wider.

[BrianFarnhill]

OK so breathing back on the embers of this one - I've actually now got the documentation model that I would rather put forward as a work in progress in my fork of SharePointDsc

Basically in the current model there are a few things we do:

1. Keep "description.md" in each resource folder with the description of each resource
2. Keep examples for each resource in /Examples/Resources/[ResourceName]/*.ps1 where the description of each example is in a PowerShell help comment at the top of the file

In the /DocoHelpers directory I have a couple of files here:

1. The first generates the PowerShell friendly help files
2. The second generates the wiki pages for git hub

Both of these processes will combine the following data in to each docoument:

• Details from the schema.mof file for each resource, including the description and parameter details
• Description from the description.md file for additional text content
• Each example in the examples folder for that resource are added and the example comment for it is formatted appropriately based on the type of document we are generating

This is way cleaner than the MOF schema comments we did - I'll update my appveyor.yml file to remove all the description.md files from a release build (theres no need for them to ship), and our build already generates the powershell help and adds that so that's covered as well. Plus we have a nice neat model for the examples as well that are specific to each resource that we can also test for parser errors because they are valid PowerShell, meaning if we make a breaking change to a resource then it should also fail the pester tests if we don't also update the examples as well.

Anyway have a kick around that branch of mine while I write up the rest of our doco over the next few days and let me know what you think. If it looks worthwhile we could look at moving the stuff from my docohelper directory in to one of the main DSC repos and pull it from there in to each resource that wanted to take this approach.

[BrianFarnhill]

@kwirkykat Would love you to have a look at what I've got here to get your opinion on it being feasible to use in multiple resources. Start with what I just posted above.

[kwirkykat]

@BrianFarnhill Love the DocoHelper scripts. Love the idea of setting up the wiki for every resource. :+1: I think the 'comment at the top' method for example (and test) documentation works well. For tests, we can also include a comment at the top for how to run the test properly (what WMF should be installed, other programs that need to be installed, any other dependencies).

The extra 'Resources' folder under the 'Examples' folder is not needed.

This is my current mock-up (not finalized) for a standard resource module structure incorporating this model of documentation:

• MyResourceModule
  • README.md (Link to license, contributing doc, code of conduct, etc)
  • MyResourceModule.md (Overview of module with links to each resource explanation)
  • Changelog.md (Unleased changes and past release notes)
  • DscResources
    • MyResource
      • MyResource.psm1
      • MyResource.schema.mof
      • MyResource.md (Explanation of resource - a.k.a. 'description.md')
  • Tests
    • MyResource
      • MyResource.Unit.Tests.ps1 (With appropriately formatted comment at top) (tests for individual functions - does not run a configuration)
      • MyResource.Configuration.Tests.ps1 (With appropriately formatted comment at top) (tests with configurations)
    • Integration (tests with multiple resources working together)
  • Examples
    • MyResource
      • MyResource.Scenario1.ps1 (With appropriately formatted comment at top)
      • MyResource.Scenario2.ps1 (With appropriately formatted comment at top)
      • Integration (examples with multiple resources working together)

We can remove any unnecessary .md files along with the appveyor.yml file before release. One other suggestion is that we could add a Documentation file in the root folder that would contain all the .md/description.md files. Then that folder could just be deleted from a release.

I'm not sure about the Pester tests failing when examples are not updated when a breaking change has occurred. How would the tests be able to tell that a breaking change has occurred rather than a smaller/not-affecting-functionality change?

[BrianFarnhill]

@kwirkykat Awesome, so a couple of things there. Firstly I have that resources folder inside the examples because I still want to provide some other examples (which don't exist yet) that are complete examples rather than resource by resource, so I figured I would separate them based on folders like "resources" and "full examples" or something like that.

Also I decided to rename the description.md files to readme.md so they show when you browse to that folder in source control on GitHub.com as well.

In terms of the "MyResourceModule.md" that you want to have, would this not just be the home page of the wiki?

Lastly in terms of the breaking changes bit - the scenario that comes to mind is one we got caught out in for SharePointDsc where we changes a property from a string to PSCredential, which broke the example and we missed it in our updates so we released a bad example. Now that the examples are full and valid PowerShell (this is why I wrap my examples in the full Configuration element) we should be able to test them for parser errors and have that written in to a pester test. So a non-breaking change might slip through the cracks if the examples are updated, but at least the stuff that will break when customers pick these up will get caught so we can help ensure we don't ship broken examples and documentation moving forward.

[kwirkykat]

@BrianFarnhill I do really like that GitHub displays the readme.md for each resource when you open it up. That's cool. I don't think it really matters much what those md files are named, so making them readme.md works fine since it adds the cool GitHub display.

"MyResourceModule.md" probably is just the homepage of the wiki, so we could take that out and then just put a link to the wiki in the README (so people who don't know about GitHub wiki's can find it).

Ok. So the pester tests would just check for parse errors in the examples. That would be great. We would probably add that to the common tests. Those example tests would help with the HQRM plans to.

Updated module structure with documentation:

• MyResourceModuleDsc
  • README.md (Link to license, contributing doc, code of conduct, wiki, etc)
  • Changelog.md (Unreleased changes and past release notes)
  • Resources
    • MyResource
      • MyResource.psm1
      • MyResource.schema.mof
      • README.md (Explanation of resource)
  • Tests
    • Resources
      • MyResource
        • MyResource.Unit.Tests.ps1 (With appropriately formatted comment at top) (tests for individual functions - does not run configurations)
        • MyResource.Configuration.Tests.ps1 (With appropriately formatted comment at top) (tests with configurations)
    • Integration (May be renamed) (tests with multiple resources working together)
  • Examples
    • Resources
      • MyResource
        • MyResource.Scenario1.ps1 (With appropriately formatted comment at top)
        • MyResource.Scenario2.ps1 (With appropriately formatted comment at top)
    • Integration (May be renamed) (examples with multiple resources working together)

[BrianFarnhill]

@kwirkykat Should the tests folder still have both "Unit" and "Integration" inside of it to group the unit and integration tests?

[BrianFarnhill]

My doco helper module is almost complete, I did have to raise another discussion with regard to taking the doco out of the readme file - linking it here as its related

[johlju]

This is being worked on in PR https://github.com/PowerShell/xWebAdministration/pull/290.