docs docs docs!

[dmccaffery]

Let's figure out how we want to implement docs. There is enough going on that a README isn't enough to contain everything and I think it makes sense to build out some better docs, but how to do it?

Couple of options:

1. Hugo (or similar) with GitHub Pages
2. GitHub Wiki

Prompt is simple and composable enough that it should be possible to document everything in the wiki with enough organisation for folks to find what they need.

I think GitHub Pages is a better alternative if we want to seamlessly integrate prompt docs with docs from any other repos in the org. It's also better if you want to force docs as part of the code; requiring it for PRs.

This decision should not come from me, but I did want to add it as an issue so it's tracked (topic keeps coming up).

[dmccaffery]

@patrickserrano @sjk07

[sjk07]

My opinion is we might as well use GitHub pages since we are using GitHub... regardless its syntax is markdown so we can always change it pretty simply in the future if needed

@patrickserrano I remember you saying you would be interested in this 😜

[dmccaffery]

I'll setup a pipeline for GitHub Pages with Hugo with an empty shell -- and hopefully @patrickserrano will start writing docs in it

[sjk07]

@patrickserrano Any ideas on what to start with? lets create the structure and get things setup in markdown. nothing stopping us from moving forward with that 🥰

[patrickserrano]

@sjk07 what about something like this?

• Getting Started
  • Installing
    • Installing pre-release
    • Installing older versions
  • Themes
  • Two line prompt overview
  • Editing your profile
• Install scripts/tools
  • SDKs
  • Tools (mini-kube, kind, Pandoc, etc)
• Scripts/aliases
  • add-var, show-vars, remove-var, open-url, etc
  • Colors
  • Platform specific (show-all, etc)

[sjk07]

@patrickserrano crap totally missed this, you should have bugged me lol!

This looks good. we should think of a way to show all things that are and are not platform specific. It would be nice to only show the functionality available to the user

[patrickserrano]

@sjk07 maybe once we have the docs put together we can look at placing the platform specific items in collapsible elements which we can auto-expand for the current platform?

[dmccaffery]

@patrickserrano / @sjk07 : couple of ideas:

1. Docsy theme (by Google) for Hugo
2. Material theme for MKDocs which is used by folks like Spotify

Let me know which ones you would like to go with; I'm happy to setup the skeleton and deployment to GitHub Pages to make it easier to just start writing content.

[dmccaffery]

@patrickserrano ^^

[patrickserrano]

@dmccaffery I really like the MKDocs site. That said, do you think that Hugo is more widely used which would make it easier for new contributions? If you don't think it matters lets go with the MKDocs theme, otherwise Docsy works too.

[sjk07]

@patrickserrano @dmccaffery I like the idea of using hugo. only because I don't like python 😜

That being said its important to keep in mind what types of tech we are using and have to support.

we have:

1. shell scripts (sh\bash)
2. starship written in rust
3. might introduce some powershell for our windows friends

I have wanted to move toward using golang for other poject's but no real skin in the game yet. end of the day we need a static site generator that take markdown and outputs html.

Any reasons we should not use Hugo?