Developer Documentation

[oneolddev]

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]

Completely acceptable, feel free to proceed.

[oneolddev]

@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]

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?)