search

sixfeetup / scaf

scaf provides developers and DevOps engineers with a complete blueprint for a new project using Kubernetes
BSD 3-Clause "New" or "Revised" License
66 stars 9 forks source link

Rewrite README with a clear overview of what the cookiecutter does and how to get started. #129

Closed rochecompaan closed 3 months ago

rochecompaan commented 10 months ago

Rewrite the README to include:

  1. A high-level overview of the project
  2. Architecture of a target project
  3. Concise usage instructions and what options are available

Remove the list of Python packages.

hillairet commented 3 months ago

I wouldn't mind taking that one on.

I would use section titles as questions such as "What is the architecture?" and HowTo such as "How to set up your local environment for development". I find that these help create focus and clarify the purpose of the section for both the writer and the reader.

Example in Beck's README

hillairet commented 3 months ago

Oh also, what about the use of emojis for section titles? I find them quite helpful when scrolling through a large single-page README.

rochecompaan commented 3 months ago

Since I logged this ticket, I have already made a few updates to the README:

Note that the README for Scaf differs from the README for the generated project.

There is a PR of an architecture diagram, but it is outdated now: https://github.com/sixfeetup/scaf/pull/126/files

I think we can close this issue and re-open more specific issues for updates to the README since the Scaf README provides a workable general overview, and the instructions for the generated project are mostly accurate.