Skip to content
This repository has been archived by the owner on Feb 2, 2021. It is now read-only.

Readme updates for better new user readability #76

Open
burtonr opened this issue Feb 20, 2019 · 2 comments
Open

Readme updates for better new user readability #76

burtonr opened this issue Feb 20, 2019 · 2 comments

Comments

@burtonr
Copy link
Contributor

burtonr commented Feb 20, 2019

Some suggestions to make the readme easier to read and follow along

Expected Behaviour

No doubt when "pulling the trigger" and executing the ofc-bootstrap. Knowing that you've completed all the steps, and set all the values properly

Current Behaviour

Having to read through the readme several times to make sure all the steps were completed and nothing was missed.

Had to go back and forth between the openfaas-cloud/docs page and here to be certain.

Possible Solution

  • Move the "Roadmap" section to a separate file
    • Possibly also the "Status" section, but I can see where that could be useful to remain
  • Add section just for the Github App setup
    • Similar to the Create Your Github App section in openfaas-cloud
    • List out the sections (in order of presence) and what value should be put there
  • Update DNS section with a little more detail
    • Call out the command to get public IP of the LoadBalancer (hidden in text)
    • Describe all the DNS fields required (A record, etc)
  • Have an explicit list of fields from the init.yml that are required to change
    • Currently, you have to read through the entire document and the init.yml file to know what needs changed
    • Without an explicit list, you have to read through everything multiple times to know you didn't miss anything
    • Check box each of the fields so users can check them off when they're complete to avoid confusion (was this the default value, or did I already update it?)
  • Different formatting for optional steps
    • The optional sections blend in and are difficult to know where they end and required steps start again
    • Maybe a quote section > to indicate the beginning and end of the optional sections?
    • Also, good to know why it's optional. "Password auto-generated", "If Running locally", etc

Other things I may have missed/overlooked?

Steps to Reproduce (for bugs)

Be a user who doesn't have extensive OpenFaaS, Kubernetes, Github App, and DNS expertise

Not really a bug

Context

Your Environment

  • FaaS-CLI version ( Full output from: faas-cli version ):
    0.8.3

  • Docker version docker version (e.g. Docker 17.0.05 ):
    18.06.2-ce

  • Are you using Docker Swarm or Kubernetes (FaaS-netes)?
    Kubernetes

  • Operating System and version (e.g. Linux, Windows, MacOS):
    Ubuntu 18.10

  • Link to your project or a code example to reproduce issue:
    N/A

  • Please also follow the troubleshooting guide and paste in any other diagnostic information you have:

@alexellis
Copy link
Member

Can we start with some small incremental changes?

@alexellis alexellis added this to Help wanted in Triage - Code/Review/Merge Mar 2, 2019
@Waterdrips
Copy link
Contributor

Might be good to have a section at to bottom of each section with "expected changed variables" so you can make sure they are all completed for sections you are interested in?
(having just done my first ofc install)

@alexellis alexellis removed this from Help wanted in Triage - Code/Review/Merge Nov 4, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

No branches or pull requests

3 participants