Readme template is not suitable for large modules

[BrianFarnhill]

The current structure of having all information for each module in the readme.md file template is not at all compatible for resources that have a large number of versions and/or resources. For example, SharePointDsc currently has 72 DSC resources (all with multiple examples) 13 separate releases with over 130 lines of detail in our changelog. To put all of this in to the readme file would result in the file being ludicrously large and hard to actually read. As an alternative I would like to propose a few changes:

1. The "versions" section should be moved to a file called CHANGELOG.md with the same details recorded there (see SharePointDsc's example)
2. The examples and descriptions of the resources should be moved out of the readme in to the wiki for each repo on GitHub

The first proposed change is pretty straightforward, but I want to make some suggestions for the second based on how we do things in SharePointDsc (including some work in progress that I'm just finishing for it now). For the second change here to work, I believe the following structure needs to be implemented.

• All examples exist in the /examples directory of the module
• All text descriptions of resources exist in a readme.md file in the folder for the resource (where its psm1 and schema.mof file exist)

With these changes, I have a module that is just about ready to release that will analyse a DSC module that is structured like this and generate the wiki pages for GitHub, but will also generate PowerShell help files for a module that can ship with it, allowing users to use the Get-Help command like this:

Get-Help about_SPCreateFarm

The wiki pages and help files include the following documentation:

• The contents of the readme.md file for a description
• Details of the schema are generated automatically from the contents of the schema.mof file, including descriptions where they are available
• Examples for the resource if they are available

This means we can remove all of this clutter from the readme file template, automate the generation of the documentation, run tests to ensure the examples are all valid (we are doing this now in SharePointDsc), and ensure that whats in the wiki matches the help in the module for consistency of documentation.

I was literally working on this code when I was asked to raise this issue, so I'll post some links with references to the specific parts shortly after I polish it up and commit it, but wanted to put it out there for discussion immediately

[BrianFarnhill]

So some of my code

Firstly, the module that generates the documentation. It has two functions (Write-DscResourcePowerShellHelp and Write-DscResourceWikiSite) which work as ive described above for generating the doco.

Then you can have a look at the outputs from our Appveyor builds for the other indicators and useful bits. You can see the tests on the examples passing, and the examples themselves are all still in the module itself for those who download it from the PS Gallery. Also if you look at the AppVeyor build artefacts for the compiled module to see the actual doco in the en-us folder to see the PowerShell help, and the wiki zip file is generated so we can just do a bulk commit of those files to the wiki.

So, after a lot of writing, we have viable options to generate the doco away from the readme file and keep that file nice and lightweight like it should be :)

[KarolKaczmarek]

Sounds great.
One thing we need to be aware of is before we will be able to adopt the help generating scripts, we need to modify our release automation to release directly from GitHub release/appveyor artifacts (since we won't have all shippable artifacts checked in, some will be generated during the build).

[BrianFarnhill]

@KarolKaczmarek Completely agree - and I think its worth looking in to linking this to AppVeyor (have a build that runs on master only or something like that? I'm not sure how that component would work off the top of my head).

In terms of my documentation helper module - would you like that in it's own repo? Or in one of the existing DscResource repos? I'll make the arrangements to move it out of SharePointDsc so we can get the ball rolling on this one

[KarolKaczmarek]

I think DscResources repo would be the right place for it.

Regarding automating it, one way to do it would be to perform build + release from appveyor artifacts whenever we tag it with PSGallery-version (since we create this tag currently for every release anyways).

[BrianFarnhill]

@KarolKaczmarek No worries, I'll put a pull request in to DscResources shortly and tag the pull request here. Once that's merged in I'll get SharePointDsc using it and that can then be the basis for some documentation on how to use it that we can put in the DscResoruces repo as well

[BrianFarnhill]

Just got the pull request for the doco helper in for review. I feel like once that is included we can look at a separate PR to update the readme template (after the doco on how to generate the doco is done, so then people can have the full picture ready to go)

[johlju]

It seems there are two outstanding work items in this issue.

1. Split the README.md into one README.md and one CHANGELOG.md in the DscResource.Template.
2. Update Wiki documentation in the build pipeline when PR is merged to master branch. I think I saw an explanation of how this was done manually today for SharePointDsc, but can't find the comment.

I suggest we split this issue into two new issues and close this one.

[johlju]

Number 1 is being done in PR #388.

[johlju]

Number 2 will be resolved in issue PowerShell/DscResource.Tests#142.