Docs how to organize project

[KucherenkoSerhiy]

⚠️   Pre Checklist

Please complete ALL items in this checklist, and remove before submitting

• I have npm run build and npm run serve locally before submitting this PR
• I have read through the Contributing Documentation

Summary

WIP, continues PR 634.

Does this close any open issues?

Closes #612

Screenshots

Other Information

I recreated the feature branch to fix a minor mistake without realizing that it force-closed the PR.

[Startrekzky]

I think we can make the definition straightforward, something like:

"A DevLake project is a grouping of pull requests, deployments, or incidents. It can be seen as a real-world project or product line. DevLake measures DORA metrics for each project."

[Startrekzky]

I came up with a simple version of the project pic, it introduced the idea of domains, i.e. repos, boards and cicd_scopes based on the original pic. What do you think?

[KucherenkoSerhiy]

It looks simple and gives a pipeline-oriented view of what is happening. Since DevLake carries much of the pipeline nature, it is accurate.

[Startrekzky]

I looked at this pic and I can understand it, but I'm worried that it might be a bit complicated for users. I have a few thoughts for your reference:

1. Make all use cases more real-life. E.g, use 2 Jira boards, 3 GitLab repos, and Deployments are executed via GitLab CI in each GitLab repo to replace the current description and the wordings in the picture.
   

2. Convert the single image to several steps according to the Config UI workflow to reduce the cognitive load so that users can follow it step by step. An example for the pic:
   

[KucherenkoSerhiy]

Yes, it is complex. Thank you for pointing out some possible ways to break it down, that is what I was looking for.

I'd rather use a different CI/CD platform to avoid possible missing points based on that you can configure both pull requests and deploys with a single connection in the case of GitLab. Using a single connection for multiple entities is a great feature, but as an example, it hides the point of seeing pull requests and deploys as completely separate entities.

[Startrekzky]

@KucherenkoSerhiy You can use CI/CD platform for sure. What I was thinking was that in some use cases, we can use CI/CD platform: GitLab CI; while in others we can use CI/CD platform: Jenkins or CI/CD platform CircleCI(via webhook). The idea is to make them more close to real life. I hope it makes sense.

[Startrekzky]

I re-thought about the annotations here. I think after we introduce the toolchains and how incidents, repos, and deployments are organized in each use case, we can

1. First, add a text summary describing how many DevLake projects should be created.
2. Then, show which boards(for incidents), repos(for pull_request), and deployments belong each project.
3. Then, add a picture with steps showing how to configure the projects in DevLake.

I think this flow will be easier to understand. Looking forward to your feedback.

[Startrekzky]

Hi @KucherenkoSerhiy , I think adding the diagrams of creating GitHub connections step by step makes the manual clearer. I suggest you adding the relative link to this doc (https://devlake.apache.org/docs/Configuration/GitHub#step-1---add-data-connections) for users to find more details to create a GitHub connection.

[KucherenkoSerhiy]

Oh, that is exactly what I was looking for but did not find on time. Thank you very much for pointing it out!

[Startrekzky]

With the example of creating a GitHub connection above, to make the doc concise and also reduce the workload, we don't need to add the steps to create connections for every other data source. Instead, we can just attach the existing URLs here.

The URLs can be found in this folder: https://devlake.apache.org/docs/Configuration, please use the relative URL.

[Startrekzky]

I think the diagram is much simpler. I only have few thoughts on the wordings:

1. To make the wording consistent, if Jira Board A is used, we should use GitHub Repo 1, Jenkins Job 1 instead.
2. To make the example more real, we can add a caption under the Scopes, such as adding "Project A's features" under "Jira Board A", "Project A's main app" under "GitHub Repo1", "Shared libraries" under "Repo2", etc.

[KucherenkoSerhiy]

Hi @Startrekzky, Thank you once again for the corrections. I am not sure I understand the second point, but I think I get it. Let me know your thoughts in any case!

[Startrekzky]

I think the 2nd level heading should be "Use Cases", then adding "Use case 1", "Use case 2" as the 3rd level headings.

[Startrekzky]

Hi @KucherenkoSerhiy , I'm not sure how you define team or project.

From my perspective, a team is an organizational concept (people-wise); while a project is a project (work-wise). Therefore, in this use case, we might use 2 projects instead of 2 teams.

Also, to make it more real, you can use the example of real-life open-source projects, for example, DevLake and [DevStream](https://github.com/devstream-io/devstream). DevLake is a project that manages 3 repos, apache/incubator-devlake, apache/incubator-devlake-website, and apache/incubator-devlake-helm-chart.

I hope it makes sense.

[KucherenkoSerhiy]

Hey @Startrekzky, thank you for the tips! Sure, 2 projects sound more coherent to DevLake.
I also left a side note that for DORA there are no teams, only projects.

Regarding DevLake, I agree and also think it should come first as a base use case. The one already in the document is rather an expansion, introducing intersections between projects.

[Startrekzky]

Haha, DevStream is not an Apache project. Let's use another project. For your reference:
"Apache DevLake and Sparks are two independent projects of ASF. Assume that ASF wants to compare the DORA metrics of the two projects. What should the ASF do?"

[KucherenkoSerhiy]

Haha, thanks for pointing out the funny mistake and guidance!

Regarding the comparing projects, I'd instead check the health of the development and maintenance with DORA of separate projects rather than compare themselves. There may be many differences between assignments (size of the team/community, problem the project solves, project's age, etc.).

Comparing the projects between themselves might mislead to why use DORA in the first place. Many companies end up having projects organized by teams, so this leads to comparing those teams.
That might lead to higher competitiveness and toxicity and create more problems instead of solving them.

[Startrekzky]

Please update it to Sparks accordingly.

[Startrekzky]

Should the "go" be removed from the sentence? I highly recommend you use ChatGPT or Grammarly to get all wording/typos fixed in this doc.

[KucherenkoSerhiy]

Sorry for the grammar clumsiness. I am used to running the Grammarly-ChatGPT-Grammarly pipeline in the end. Also, the files need to be sorted after finishing everything.

[Startrekzky]

I retook the screenshots to make it look better.

[Startrekzky]

Is the arrow pointing to the dashboard menu missing here?

[Startrekzky]

This is awesome. So clear.

[Startrekzky]

Q&A? QA usually refers to quality assurance.

[Startrekzky]

Normally, we don't recommend users to create multiple connections for a shared data scope, for instance, GitHub repos. This will increase the time to collect the data because the shared repos will be stored in multiple copies in the DB. See pic:

Instead, we encourage users to create ONE connection and add all data scopes (p-1, p2, ... , p-10, it-legacy-1, it-legacy-2) in the Data Connection page, and when users:

• bind this connection to Project payments, they only need to choose 'p-1, p2, ... , p-10'
• bind this connection to Project it-legacy, they only need to choose 'it-legacy-1, it-legacy-2'
  In this way, the data of 'p-1, p2, ... , p-10, it-legacy-1, it-legacy-2' will only be stored in a single copy. That is to say, the sync-up time will not be doubled/tripled either.

So, in my opinion, there should be a '4.2.0. Create Data Connections' before 4.2.1. And the current '4.2.2. Adding Connections' should be renamed to '4.2.2. Adding Connections and repos to Projects'

[KucherenkoSerhiy]

That's a great point. In fact, I think it's good to mention that in the guide.

[Startrekzky]

LGTM. @KucherenkoSerhiy Thanks for your continuous input. I'll merge it first and refine it (mostly about the flow and wording) within the next week.