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

Update README/docs to better reflect the purpose of Maggma #886

Closed
Andrew-S-Rosen opened this issue Nov 13, 2023 · 1 comment · Fixed by #969
Closed

Update README/docs to better reflect the purpose of Maggma #886

Andrew-S-Rosen opened this issue Nov 13, 2023 · 1 comment · Fixed by #969
Assignees
Labels
docs documentation

Comments

@Andrew-S-Rosen
Copy link
Member

Andrew-S-Rosen commented Nov 13, 2023

Problem

In talking to colleagues unfamiliar with maggma, when they check out the repo, it seems there is some (justifiable) confusion about the main purpose of the package.

For instance, the "About" section on the GitHub sidebar says "MongoDB aggregation machine", which of course is how the name was derived, but it leads visitors to believe that it is a package only for MongoDB when in reality there are many data stores.

The README says "A files-to-API data pipeline," but in fact, many of the data stores do not rely on the filesystem at all. The same point can be made for the "What is Maggma" section of the documentation.

In general, it is not immediately clear the purpose of Maggma from the docs, and there is a lot of jargon once you dive into the docs.

Proposed Solution

  1. Come up with some clearer branding on the README and "What is Maggma" section.
  2. Add a "quickstart" section to the Maggma docs, before the Core Concepts, that shows a common minimal example. For instance, instantiate a MongoStore, upload a toy result, and query it.

Alternatives

No response

@Andrew-S-Rosen Andrew-S-Rosen changed the title [Feature Request]: Update README/docs to better reflect the purpose of Maggma Update README/docs to better reflect the purpose of Maggma Nov 13, 2023
@rkingsbury rkingsbury added the docs documentation label Nov 14, 2023
@rkingsbury
Copy link
Collaborator

Great ideas @Andrew-S-Rosen , I am strongly in favor (and have been wanting to do something like this for a while.) I am happy to take a stab at it, but it will likely be mid-December of later before I can do it. I'll tackle #702 at the same time.

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

Successfully merging a pull request may close this issue.

2 participants