Improve onboarding documentation
BenHenning opened this issue · comments
The current onboarding documentation is a bit thin, and may not be super easy to follow. The following improvements should be made:
- Easy way to get to the onboarding instructions (e.g. via a README--this should be solved with #560)
- Ensure the onboarding flow leads into follow-up documentation: architecture overview, code style, submission guidelines, how to make UX changes, how to contribute large projects (which should tie into design documents), and best practices #5174
- Ensure there's supporting documentation for all key technologies: data-binding, Bazel, Kotlin, and Android development (suggest linking to a bootcamp to help people get started)
- Ensure the installation instructions provide support for folks both using emulators and physical Android devices
- Ensure there's a cheat sheet for quick operations: running the app, building & running tests, running the linter, etc.
- Ensure there's a page providing guidance on making code changes (including dealing with Bazel)
- Known issues that have come up in discussions #5174
Reaffirming the need especially for clear instructions on how to run tests.
I would like to work on this!
Can you please assign it to me?
@UvrajSB I think that this issue might need some revising before it can be divided up.
@MaskedCarrot do we have a more updated list for documentation work items?
@BenHenning The dev-workflow team has a documentation tracker that contains wiki pages and their progress.
@MaskedCarrot are all of the above accounted for in the tracker (and, if not, should they be?)? It'd be nice to have a single source of truth so that we don't have potential confusion around where to look for things.
That being said, there probably ought to be a tracking issue on GitHub for the work (even if it just points to the tracker). Does one exist?
@BenHenning No, not all of them are in the tracker. I will discuss this with the welfare and the dev-workflow teams and file issues for all the wiki pages that need to be updated.
@BenHenning No, not all of them are in the tracker. I will discuss this with the welfare and the dev-workflow teams and file issues for all the wiki pages that need to be updated.
Thanks @MaskedCarrot! Can you update this task once that's completed? (Either by linking to the new issues & tracker and closing this, or by updating it and mentioning that it's the source of truth for changes).
I would like to work on this! Can you please assign it to me?
@UvrajSB You should work with your onboarding mentor to find technical work to do. Documentation can be really difficult to write if you don't have the needed technical context for the project, so I suggest submitting a few PRs before working on documentation changes (however, once the PRs are merged, you can reach out to @MaskedCarrot to see what's available).
@MohitGupta121 PTAL. Not all of the checkboxes are easy to handle but let's at least track the ones that are easy, and check those off here once they're done. Thanks!
@seanlip Thanks Sean, this really helps to track.
Also as a follow-up, these ought to be entirely focused on Bazel at this point @MohitGupta121 since there's not much value in writing out Gradle-based instructions with the plan to remove Gradle in the next 1-2 months.
@BenHenning Yes I keep the Bazel thing in mind, but First I think we need to go with installation and setup of Bazel, then we move to other flow and documents.
What you think?
@BenHenning If possible, Can you please update the Issue description Points that we need step by step work on.
Thanks.
Yep completely agree @MohitGupta121.
@BenHenning If possible, Can you please update the Issue description Points that we need step by step work on. Thanks.
Sorry not sure what this means--could you clarify what needs to be updated?
Sorry not sure what this means--could you clarify what needs to be updated?
I talking about the issue task list, I think we need to update the description task list. It's was not seems out of dated?
We need to add some more things like debugging with Bazel, Basic of Bazel that we are planning?
I think all of the tasks listed are worthwhile @MohitGupta121, but if any are fully or partially completed, feel free to edit the main comment & link to the corresponding wiki pages (and tick off items if they're completed).
Okay Thanks @BenHenning, I will follow these instructions.