PowershellFrameworkCollective / psframework

A module that provides tools for other modules and scripts
MIT License
435 stars 41 forks source link

Need a THOROUGH example #576

Open merddyin opened 1 year ago

merddyin commented 1 year ago

I realize that this project hasn't been touched in a LONG time, aside from a minor update a couple months ago, but felt like I should post anyway. I know there is already an issue logged related to documentation. As a technical type person, I realize that documentation is a pain to write, which is probably at least partially why it still isn't done. I propose a slightly different approach however, and one that might help others with contributing to documentation...I propose that the original maker create a demo module that leverages all of the features, with reference comments on the relevant elements showing how they relate to each other. Yes, I know there are at least some modules here and there that leverage some aspects of PSFramework, but actually finding any that are complete has proven exceedingly difficult thus far, since there doesn't seem to be a tag for them for anything in the gallery, nor have I found a list of projects anywhere. For something that's been downloaded over 3 million times, you'd think there'd be something. If someone knows of a list somewhere, or a way to search for projects using the framework, please do share.

Now, this example project doesn't need to do anything monumental, it just needs to show a working module that demonstrates the use of the various features of PSFramework in a cohesive manner, meaning all the parts are functional elements of the example module. Again, the key elements here are 'working' and 'cohesive'. Yes, I've seen the examples when you use the associated PSModuleDevelopment, but most are neither functional nor cohesive. I've also seen the documentation site, and the quick starts, but again, they lack sufficient cohesiveness to enable me to put all the pieces together without a bunch of trial and error. I'd like to use this framework to simplify how I build my modules, but I don't have time to figure out both my own module and this one.

Thoughts?

FriedrichWeinmann commented 1 year ago

Hi Chris,

a fair point for sure! I'll be honest, putting something together that includes all the feature and the term "cohesive" are mutually exclusive (we're talking about a huge amount of them, many minor and specific to a special scenario). That said, I can definitely put together a documented example project for the main feature-sets.

Specifically ...

It'll be a bear to finish end to end, but as you said probably worthwhile from seeing it in action and how the parts fit together. I literally can't promise a timeline - one of the key reasons for the slow progress is the mountain of work I'm buried under and some other complications in my life - but it would probably be a better time-to-result ratio than polishing up the docs in full detail.

It would also be a great addition for when I do add pages to the documentation website, allowing me to link to a full example that can be ran, tested and played with.

As for finding projects using it:

Find-Module | Where-Object { $_.Dependencies.Name -contains 'PSFramework' }
merddyin commented 1 year ago

So, to be clear, not asking you for documentation necessarily...comments would be sufficient, for myself at least. Also, if you are working through the project with regular check-ins on a GitHub, people could follow along. I'm a consultant for a living so documenting things is something I do often, and I would be happy to participate as a contributor in that regard as I follow along with your project and come to understand things better.

I can understand using all the features being difficult, since you wouldn't necessarily always need to use runspaces for example. I think a project that links together commonly paired features with the most popularity would be fine, and you could add other projects over time. Alternatively, if there are projects already using the framework that demonstrate the desired implementation, I'd be just as happy with a referral to that project in a blog post that provides commentary on the PSFramework elements that they are correctly leveraging.

In all, I guess I've just become frustrated every time I've tried to use your framework because I couldn't figure out how to properly leverage most of the elements from the documentation alone, and I couldn't find any good examples. Making someone separately install two modules just to gain the functionality of one was another challenge that meant I really needed to justify the benefits of the framework versus other options. For comparison, I currently typically use the ModuleBuilder template framework, which provides simplifications via a 'plugin' type system that basically lets me sort of bundle a supporting module (license permitting) within my own module package. I generally only use the nlogmodule as a plugin to provide transparent logging, but I have periodically needed other functionality as well. Your framework however, provides a number of tantalizing enhancements that would require multiple separate plugins to achieve otherwise...though it would mean that someone has to separately install a module they may never use directly, but meh.

Callidus2000 commented 1 year ago

Just as an alternative idea: what about a new repository for creating a new example driven documentation? It could provide explanations combined with example code and perhaps reference to existing code in other repositories. I'd be very happy to contribute as I've been using PSF for many years and in all my modules. Fascinating fact is even I've used it for almost everything it provides I imagine that I've only scraped 40% of all functionality (large bit of the iceberg).