Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update docs #8

Open
c10k-cc opened this issue Oct 18, 2022 · 3 comments
Open

Update docs #8

c10k-cc opened this issue Oct 18, 2022 · 3 comments
Assignees
@c10k-cc
Labels
issue::crossrepo Issue which relates to multiple project repositories issue::docs Issue which addresses improvements or additions to documentation issue::enhancement Issue which addresses a new feature request or proposal issue::helpme Issue which requires extra attention from other contributors issue::meta Issue which addresses the project organisation, workflow and / or repository itself issue::newcomers Good for newcomers or first-time contributors

Comments

@c10k-cc
Copy link
Contributor

c10k-cc commented Oct 18, 2022 •
edited

Update docs

Summary

This issue / proposal attempts to address the project's need for a proper documentation update.

Description

Type of docs which need to be updated / added (including but not limited to):

  • project-related docs
    • rust docs
      • Rust doc-string comments inside the code files which gets auto-rendered to API reference docs - see more here
      • fix cross-linking / cross-referencing
    • README.md
      • file needs to be properly re-structured to reference all other markdown files proposed below
      • sections need to be sorted by the degree of complexity / depth of the topic covered
    • ARCHITECTURE.md
      • describes the project architecture
      • could contain an embedded diagrams (UML or less formal) & flowcharts
    • Concepts
      • covering various concepts (theoretical or otherwise) introduced by the project
      • glossary of terms for the project
    • Examples
      • simple & trivial examples covering various project functionalities
    • Tutorial
      • proper user guide
    • Quick start
      • see 2 sections above
  • repo-related docs
    • CONTRIBUTING.md
      • contains instructions on how to contribute
      • how to write code, tests, docs, git commit, git branches / workflow, setup dev environment etc
    • MAINTAINING.md
      • contains instructions on how to maintain the repo
      • how to manage & review issues / pull requests, organise the project board etc
    • CODE_OF_CONDUCT.md
      • bullshit file covering various topics related to political correctness, inclusivity, racism, sexuality, hate speech, profanity etc.
      • mainly used as a diplomatic no-responsibility disclaimer guarding authors & maintainers from consequences of stupid shit & abuse some degenerate contributor might do and ruin the things for the whole community
      • nice to have, but definitely lowest priority ever
  • dedicated docs site / wiki pages
    • GitHub Wiki pages?
    • currently redundant?
@c10k-cc c10k-cc added issue::docs Issue which addresses improvements or additions to documentation issue::enhancement Issue which addresses a new feature request or proposal issue::newcomers Good for newcomers or first-time contributors issue::helpme Issue which requires extra attention from other contributors labels Oct 18, 2022
@c10k-cc c10k-cc self-assigned this Oct 18, 2022
@c10k-cc c10k-cc added issue::crossrepo Issue which relates to multiple project repositories issue::meta Issue which addresses the project organisation, workflow and / or repository itself labels Oct 18, 2022
@Traumflug
Copy link

Rather than planning for top-notch documentation, a simple set of instruction on how to get the example or these code snippets running at all would be a huge win. Is it just git clone ... cargo run ? There's zero hint on how to get things going, no hint on how the GUI(?) or CLI output looks like.

@min2sia
Copy link

min2sia commented May 16, 2023

Rather than planning for top-notch documentation, a simple set of instruction on how to get the example or these code snippets running at all would be a huge win. Is it just git clone ... cargo run ? There's zero hint on how to get things going, no hint on how the GUI(?) or CLI output looks like.

Fully agree. A quick start guide would be really nice.

@DAMIEN-C00KE
Copy link

Rather than planning for top-notch documentation, a simple set of instruction on how to get the example or these code snippets running at all would be a huge win. Is it just git clone ... cargo run ? There's zero hint on how to get things going, no hint on how the GUI(?) or CLI output looks like.

Great Idea. This is something I'd be happy to help with, and will look into.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees

@c10k-cc c10k-cc

Labels
issue::crossrepo Issue which relates to multiple project repositories issue::docs Issue which addresses improvements or additions to documentation issue::enhancement Issue which addresses a new feature request or proposal issue::helpme Issue which requires extra attention from other contributors issue::meta Issue which addresses the project organisation, workflow and / or repository itself issue::newcomers Good for newcomers or first-time contributors
Projects
Barter Project
Status: Todo
Milestone
No milestone
Development

No branches or pull requests
4 participants
@Traumflug @min2sia @c10k-cc @DAMIEN-C00KE