PowerShell/Polaris

Revamp docs

TylerLeonhardt opened this issue · 5 comments

TylerLeonhardt commented

Polaris has gone through a lot of iterations since the first docs I wrote.

It's time to address the gap. Let's get off of Github wiki and just use a docs folder so folks are able to contribute to it

Tiberriver256 commented

Can we flesh this out a bit more and maybe chunk it up into goals / tasks we can check off?

Some Ideas

  • Website maybe? (If we create a branch called gh-pages index.html from that branch will be served at http://PowerShell.github.io/Polaris which would be sweet)
    • Intro to Polaris / what is Polaris?
    • Getting started guide
    • Full guide on Routing (similar to here)
    • Simple route tester similar to here for help on making the routes and seeing what parameters come through
  • Better API Documentation
    • Ensure every function parameter is has a description
    • Ensure every function has at least 2 examples with description of what the code will do
    • Ensure every function has a full description of what that function does
    • Ensure every class has documentation
    • Ensure every property and method on classes have documentation
  • Walkthroughs / Blogs / Additional frameworks built on Polaris
    • Write some ourselves?
    • Link to a community owned awesome-polaris repo for sharing blogs / tools / things related to Polaris
  • Troubleshooting / Questions
    • Gitter chat for the repo or #Polaris channel in powershell.github.io
    • Stackoverflow tag for related questions

I like the stackoverflow option as this sort of builds itself into a knowledge base after quite a few years.

Let's discuss / add some more ideas here and pick the best ones and break them off into their own small enough Issue #'s maybe?

TylerLeonhardt commented

@Tiberriver256 I like the gh pages idea! Also, Now has free Docker container hosting so we can have live demos of Polaris hosted examples 😄

  • 👍1
  • 🎉1
TylerLeonhardt commented

Each of the main bullet points should be an issue and then sub bullets can be check boxes in those issues.

Issues:

  • Docs website
  • Better API Documentation
  • setup and create initial Walkthroughs / Blogs / Additional frameworks built on Polaris
  • setup community - gitter, slack, Stack Overflow
  • 👍1
TylerLeonhardt commented

I just want to say that for the docs website, it should all be generated from markdown. We can leverage a PowerShell module to convert markdown into html or something

  • 👍1
Tiberriver256 commented

Opened related issues. Closing this main one out.