search

emanuelen5 / kitchen-timer

0 stars 0 forks source link

README files #47

Open nperozzi opened 1 month ago

nperozzi commented 1 month ago

NOTE: Now that I know that we can discuss topics as Issues, I will go nuts with the issues 😀 !!!

This issue is to discuss how to structure the README files. We talked about it once but I have little space in my memory so I forgot 😓 .

This is how I think we can structure README files (Largely inspired in kinx project and ChatGPT suggestions):

Main README:

  1. Introduction:
    1. Quick Description
    2. Motivation
    3. Features
  2. Table of content
  3. Software
    1. Description: Brief overview of the software component.
    2. Requirements: Dependency from software versions or external libraries
    3. How to set up the toolchain?
    4. How to install the firmware?
    5. Debugging instructions
  4. Hardware
    1. Description: Overview of the hardware components
    2. Hardware BOM
    3. Schematics
    4. Assembly instructions
  5. Mechanical
    1. Description: Overview of mechanical components and design.
    2. CAD Files: Links to or images of CAD designs.
    3. Assembly Instructions: Instructions for assembling the mechanical parts.
  6. Usage
    1. Power on
    2. Setting timers
    3. ...
    4. Other features
    5. Command prompt

README file in each library folder:

  1. Title
  2. What is this library used for?
  3. API Reference: Description of functions and objects provided by the library.
  4. Configuration: Any configuration variable that the library supports (ex: max number of state machines)
  5. Usage: How to implement the library in a generic main file (maybe an example too)
nperozzi commented 1 month ago

One more note: If we have a README file for each library, shouldn´t we separate the libraries into folders?

emanuelen5 commented 1 month ago

One more note: If we have a README file for each library, shouldn´t we separate the libraries into folders?

I don't think we need a README for each library. Most of them are easy to understand since they have code that references them. However, I do think that we should explain the sketches / envs, since we need to describe what the minimal setup is required for testing each one of them, and what the expected outcome is.

As a note: We had the libraries in separate folders a while back. But, in 6de6451610f1a4197224e9a18b1edc7b60533f7a I decided that we didn't really benefit from having two files in each folder, with the same name (like lib/timer/timer.cpp and lib/timer/timer.h).

nperozzi commented 1 month ago

Understood: no README for libraries but yes for the sketches/envs. 👍😄