-
Notifications
You must be signed in to change notification settings - Fork 7
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
Conversation
4f95e8c
to
489a3e7
Compare
489a3e7
to
93d98c2
Compare
Contains all the stores. | ||
|
||
├── systems | ||
*??* |
There was a problem hiding this comment.
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.
There was a problem hiding this 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.
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. |
@kgodey @seancolsen I have closed this PR and the corresponding issue. Moving both of them to the |
Fixes #85