[Feature] Add Project Structure to Contributing Section of README

[naishasinha]

Problem

The current README lacks a clear description of the Quantifying project's structure, making it possibly difficult for contributors to understand how the project is organized.

Description

Adding a structured layout of the project will provide contributors with a clear understanding of the project's organization and help them navigate through different components easily. This will include a hierarchical representation of directories and files with descriptive comments, similar to the example provided in the Additional Context section. This will also be useful in the future for data flow purposes.

NOTE: Since this repository is relatively too big to fit everything in one page or document, it may be better to split it into different sections by folder.

Alternatives

One alternative is to leave the README unchanged or put it in CONTRIBUTING.md instead, but this would result in a lack of clarity for contributors trying to understand the Quantifying project's structure specifically, because there is no separate CONTRIBUTING.md file for this repository. Providing this structured layout directly in the README is a more user-friendly approach and enhances the overall contribution experience.

Additional context

This enhancement aligns with our goal of improving documentation and making the project more accessible to contributors. By clearly outlining the project structure, we aim to streamline the onboarding process for new contributors and facilitate collaboration within the community.

Implementation

• [x] I would be interested in implementing this feature.

[TimidRobot]

@naishasinha I expect this issue to be resolved during Google Summer of Code (GSoC), but if people want to discuss directory organization proposals, I think that would be helpful. I recommend you remove the screenshot from the issue description and then submit a comment with your proposed structure, formatted in markdown.

• This issue is labeled 🚧 status: blocked because no pull requests (PRs) should be opened for it
• This issue is labeled 💬 talk: discussion because discussion here in this issue is encouraged

[TimidRobot]

I was imagining something like:

• code/
  • 0query_flickr.py
  • 0query_google_custom_search.py
  • ...
  • 1process_flickr.py
  • 1process_google_custom_search.py
  • ...
  • 2report_flickr.py
  • 2report_google_custom_search.py
  • ...
  • quantify.py (contains shared code)
• data/
  • 2024Q1/
  • 0query/ (contains all data retrieved during query phase)
  • 1process/(contains all processed data)
  • 2report/ (contains reports)
  • ...
  • current/ (symlinked to current/most recent YYYYQQ/2report/)

I think the query and process phases need to be separate because queries might take multiple days (multiple GitHub Action runs). However, it may be that no post-query-processing is necessary and only a query phase and a report phase are needed.

I haven't fully thought this out--don't feel limited by this!

[naishasinha]

@naishasinha I expect this issue to be resolved during Google Summer of Code (GSoC), but if people want to discuss directory organization proposals, I think that would be helpful. I recommend you remove the screenshot from the issue description and then submit a comment with your proposed structure, formatted in markdown.

• This issue is labeled 🚧 status: blocked because no pull requests (PRs) should be opened for it
• This issue is labeled 💬 talk: discussion because discussion here in this issue is encouraged

Sounds good, thank you!