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.

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

Developer Documentation #117

Open
oneolddev opened this issue Nov 10, 2021 · 3 comments
Open

Developer Documentation #117

oneolddev opened this issue Nov 10, 2021 · 3 comments
Assignees

Comments

@oneolddev
Copy link

I've been stalking this project for several months and found the goals for this project admirable. I originally intended to contribute by providing docker support to simplifying onboarding new developers. But before I could start, I needed more information on the architecture and technology stack behind this project. I ran across the issues mentioned in #82 - lack of documentation.

I've spent several hours going through, the Wiki, readme files, issues tracker and CodeTour. Quite a bit of information about the system is documented but is scattered. I liked the way the Wiki was used as a way of gathering the requirements for the project. It was primarily focused on the objective with a little implementation detail. There was sufficient information readme files for the front-ends and back-end to get them built.

What was lacking was a big picture view of all the interconnected parts and dependencies.

I would like to propose that we create a docs folder for each of the front-ends, the back-end and the root.

  • \docs
    • documents that are relevant to the Two Weeks Ready
    • architecture diagram
    • description of source code layout
    • developer getting started guide
    • authorization and authentication
    • 3rd party dependencies
  • \2wr-app\docs
    • documents specific to the implementation of the app
  • \admin\docs
    • documents specific to the implementation of the admin portal
  • \api\docs
    • documents specific to the implementation of the api service

The objective is for a new developer to be able to get a good overview of the project from the documentation at the root of the project first. Then, look at the specific details of the component to which they wish to contribute.

I have a draft of an overview and architecture diagram but would like to know if this approach is acceptable. I'm also looking for further feedback and suggestions 😃.

@codingbandit
Copy link
Collaborator

Completely acceptable, feel free to proceed.

@oneolddev
Copy link
Author

@codingbandit

Can we label this issue documentation?

As I started this process, I realized that there are many things that we can document to enable faster onboarding other than a generic technical overview. The obvious one is a Build Guide for developers - step-by-step instructions to create a buildable and debuggable system.

What are the priority items that need to be documented?

@oneolddev
Copy link
Author

From #78, cover the following

  • Installations (what do i need to install?)
  • Configuration (what do i need to configure?)
  • Running (what do i need to run?)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants