getporter/porter

Epic: Porter Docs v2 Strategy

Opened this issue · 4 comments

phillipgibson commented

What design is being proposed?
v2 documentation strategy that is more operations focused, as well as easily consumable for developers/operators to contribute.

Additional Context
This will be a redesign of the current documentation to look at the possibility of rebranding components as well as promoting the brand awareness of around the bundles concept.

Risks/Concerns
Currently there are opinions that Porter suffers from a misunderstanding in the IaC operators community. Providing more clear use cases and integrations with other tooling will help demystify Porter as a competing deployment mechanism to other IaC tools.

What other approaches were considered?
A new documentation ToC has been agreed upon to help with the flow of content. The v2 design will be a more durable layout of the content to build upon for future features and content.

Implementation details
TBD

Checklist

  • An announcement of this proposal has been sent to the Porter mailing list: https://getporter.org/mailing-list
    NOTE - this was discussed on the 6/29/23 community call
  • This proposal has remained open for at least one week, to allow time for community feedback.

Current Document Issues to be resolved

phillipgibson commented

Planned ToC to promote branding/associating "bundle" with Porter.

  • Getting Started
    • What is Porter?
    • Concepts and Components
      • link list
    • QuickStart
    • Create a Bundle
  • Configuring Bundles
  • Bundle Operations
    • link list
  • Bundle Administration
    • link list
  • Bundle Development
    • Authoring a Bundle
    • Developing Mixins
      • link list
  • Porter Operator
  • Community & Contributions
  • References
  • FAQ
AGMETEOR commented

Hey @phillipgibson not sure if this is directly relatable to this epic, but I think we need to have more videos like this https://www.youtube.com/watch?v=ciA1YuGOIo4&list=PLF5fz9O0HbyrtC_bnmKkaQlS5Wvz_OmD4&index=7 showing how to deploy different applications on different cloud providers. PS: Hoping to get a Twitter page for getporter :)

  • ❤️1
phillipgibson commented

Yes that will fall into this as well @AGMETEOR

  • 👍1
schristoff commented

We have a rough outline of our new headers, and where all corresponding documentation should go here.
But there are a couple of naming sections that we would love feedback on.

What should we call documentation that is focused towards current or active users of Porter? This documentation focuses on debugging, logging, and advanced topics.

What do we call premade or established mixins? Maybe premade mixin works 🤷‍♀