search

ticketmaster / poshspec

Infrastructure Testing DSL running in Pester
MIT License
183 stars 32 forks source link

Documentation Transition #46

Open michaeltlombardi opened 7 years ago

michaeltlombardi commented 7 years ago

This project's documentation is somewhat limited. I suggest migrating towards a documentation solution using either MkDocs or GitBook.

Expected Behavior

Users should be able to access a documentation site for the project which includes tutorials, design explanations/concept guides, and reference materials. Preferably, this documentation should be versioned, available as a downloadable artifact, source controlled, and built automatically via CI.

Current Behavior

Documentation exists in limited form as wiki articles in the project, though these are not always up to date.

Possible Solution

We could use either MkDocs or GitBook to create the documentation site. GitBook can also be used to export to PDF/epub/mobi format for artifact download.

I suggest breaking documentation into three broad parts:

  1. Tutorials: This section includes more blog-like documentation conversationally walking prospective users/developers through using and interacting with the project. This is a perfect place to give an example of how to create a plugin or how to set permissions for a role.
  2. Guides: This section is more like an informal set of white papers or design documents explaining design decisions, security concerns, and other topics not best suited to a blog format but which still need to be covered.
  3. Reference: This section is where all of the actual reference documentation (exported comment based help, class references, etc) belong.

Context

I have found that this type of documentation makes using a project much easier from both a normal user standpoint as well as from a contributing developer standpoint. It doesn't have to be written all at once but providing a base level of useful documentation and then iterating on it can help to drive adoption and help answer questions about the project more easily.

michaeltlombardi commented 7 years ago

I'm 100% willing to do a first dry run or mockup of what both gitbook and mkdocs would look like for this project and submit PRs for both so you can review. Of course, if you go in either direction, I'll work to ensure that there are sane tests for documentation as well as ensure that the documentation is included in CI.

kort3x commented 6 years ago

could you give a status update?

michaeltlombardi commented 6 years ago

I haven't done any work on this since early 2017 but if there's interest I could pick it up sometime in the next few weeks - my bandwidth is a bit lower than usual right now but I can make some time.