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

Frontend code docs in wiki #86

Closed
wants to merge 6 commits into from
Closed

Conversation

rajatvijay
Copy link
Contributor

Fixes #85

@rajatvijay rajatvijay added the status: review In review label Mar 15, 2023
@rajatvijay rajatvijay marked this pull request as ready for review March 15, 2023 12:24
Contains all the stores.

├── systems
*??*
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@seancolsen will need your help here to define what it contains correctly.

@kgodey kgodey added this to the v0.1.2 milestone Mar 15, 2023
@pavish pavish self-assigned this Mar 15, 2023
@pavish pavish self-requested a review March 15, 2023 13:23
Copy link
Contributor

@seancolsen seancolsen left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks for working on this, @rajatvijay!

Some thoughts:

  • Best place for this doc

    I'm hesitant to put this sort of documentation on the wiki because it's the kind of thing that needs to be updated in tandem with specific code changes. I'd rather put this into a markdown doc in the repo that we link to from a few other places. That way we can update it along with PRs that update the code too. I'm fine with merging it into the wiki for now, and then sticking it in the main repo once we're done with this round of edits.

  • "Rendering Architecture" section

    This is great. Super helpful content to have.

  • I made a bunch of edits in f352e03 to improve the content around stores.

  • "Navigating the directory structure" section

    I'll be honest I rather dislike docs content like this. I'd prefer to remove this section.

    As a reader, when I see things like "3rd-party-apis -- Contains all 3rd party api calls" and "stores -- Contains all the stores.", my eyes just glaze over and I start to question the value of the documentation I'm reading. My guess is that most of these directories will be sufficiently self-evident to new devs. But where they are not self-evident, we should provide documentation in README.md files within those directories. The component-library directory already has this. We should consider adding more files like that, and not just at the top level either. Like, what is "systems"? Well... I don't think we're very clear on that. I think Pavish and I sort of thought we had a shared understanding of its purpose, but then we later realized we had slightly different definitions for "systems". Some of that code should probably be better organized. This is to say: it's hard to document something that doesn't have a clear answer or meaning or structure. This is a code structure problem, not a documentation problem.

  • "Form library" section

    Side note: I would like to document this better at some point. My hope is that maybe someday it would also become its own library, with its own documentation. We'll see.

@kgodey
Copy link
Contributor

kgodey commented Mar 20, 2023

Best place for this doc

Rather than spreading documentation across the wiki / docs / repo READMEs, I think we should standardize on the docs site. I set up a "Contributing" section for this purpose. I would also move stuff that's in other repo READMEs to the docs.

@rajatvijay rajatvijay closed this Mar 21, 2023
@rajatvijay
Copy link
Contributor Author

@kgodey @seancolsen I have closed this PR and the corresponding issue. Moving both of them to the mathesar repo so that this documentation can go to our docs website.

@seancolsen
Copy link
Contributor

@kgodey

I think we should standardize on the docs site

I see some challenges with this approach and I'd like to discuss this topic at an upcoming meeting. I've added a topic to our agenda with a summary of my thoughts.

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

Successfully merging this pull request may close these issues.

Create frontend codebase docs helping GSoC student to get on-boarded faster and independently
4 participants