medplum · mattwiller · Sep 26, 2023 · Sep 20, 2023 · Sep 22, 2023 · codyebberson
@@ -19,35 +19,51 @@ Medplum is a developer platform that enables flexible and rapid development of h
   - [Codebase](#codebase)
     - [Technologies](#technologies)
     - [Folder Structure](#folder-structure)
-  - [First time setup](#first-time-setup)
 
 ## Contributing
 
 **We heartily welcome any and all contributions that match our engineering standards!**
 
-That being said, this codebase isn't your typical open source project because it's not a library or package with a limited scope -- it's our entire product.
+That being said, this codebase isn't your typical open source project because it's not a library or package with a
+limited scope -- it's our entire product.
 
 ### Ground Rules
 
 #### Contributions and discussion guidelines
 
 By making a contribution to this project, you are deemed to have accepted the [Developer Certificate of Origin](https://developercertificate.org/) (DCO).
 
-All conversations and communities on Medplum agree to GitHub's [Community Guidelines](https://help.github.com/en/github/site-policy/github-community-guidelines) and [Acceptable Use Policies](https://help.github.com/en/github/site-policy/github-acceptable-use-policies). This code of conduct also applies to all conversations that happen within our contributor community here on GitHub. We expect discussions in issues and pull requests to stay positive, productive, and respectful. Remember: there are real people on the other side of that screen!
+All conversations and communities on Medplum are expected to follow GitHub's [Community Guidelines](https://help.github.com/en/github/site-policy/github-community-guidelines)
+and [Acceptable Use Policies](https://help.github.com/en/github/site-policy/github-acceptable-use-policies). We expect
+discussions in issues and pull requests to stay positive, productive, and respectful. Remember: there are real people on
+the other side of the screen!
 
-#### Reporting a bug or discussing a feature idea
+#### Reporting a bug or proposing a new feature
 
-If you found a technical bug on Medplum or have ideas for features we should implement, the issue tracker is the best place to share your ideas. Make sure to follow the issue template and you should be golden! ([click here to open a new issue](https://github.com/medplum/medplum/issues/new))
+If you found a technical bug on Medplum or have ideas for features we should implement, the issue tracker is the best
+place to . ([click here to open a new issue](https://github.com/medplum/medplum/issues/new))
+
+### Writing documentation or blog content
+
+Did you learn how to do something using Medplum that wasn't obvious on your first try? By contributing your new knowledge
+to our documentation, you cna help others who might have a similar use case!
+
+Our documentation is hosted on [medplum.com/docs](/docs), but it is built from [Markdown](https://www.markdownguide.org/)
+files in our [`docs` package](https://github.com/medplum/medplum/tree/main/packages/docs/docs).
+
+For relatively small changes, you can edit files directly from your web browser on [Github.dev](https://github.dev/medplum/medplum/blob/main/packages/docs/docs/home.md)
+without needing to clone the repository.
 
 #### Fixing a bug or implementing a new feature
 
-If you find a bug on Medplum and open a PR that fixes it we'll review it as soon as possible to ensure it matches our engineering standards.
+If you find a bug and open a Pull Request that fixes it, we'll review it as soon as possible to ensure it meets our engineering standards.
 
-If you want to implement a new feature, open an issue first to discuss what it'd look like and to ensure it fits in our roadmap and plans for the app.
+If you want to implement a new feature, open an issue first to discuss with us how the feature might work, and to ensure
+it fits into our roadmap and plans for the app.
 
 If you want to contribute but are unsure to start, we have [a "good first issue" label](https://github.com/medplum/medplum/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) which is applied to newcomer-friendly issues. Take a look at [the full list of good first issues](https://github.com/medplum/medplum/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) and pick something you like!
 
-Want to fix a bug or implement an agreed-upon feature? Great, jump to the [local setup instructions](#first-time-setup)!
+**Ready to get started writing code?** Follow the [local setup instructions](https://www.medplum.com/docs/contributing/local-dev-setup) and jump in!
 
 ### Codebase
 
@@ -90,10 +106,6 @@ medplum/
 └── scripts          # Helper bash scripts
 ```
 
-### First time setup
-
-See developer setup documentation: https://www.medplum.com/docs/contributing
-
 ## License
 
 [Apache 2.0](LICENSE.txt)

@@ -29,7 +29,8 @@ Medplum's process for Lambda Layers is straightforward:
 
 If you're hosting Medplum on your own infrastructure, remember that Bot layers don't auto-publish. To update the Bot Layer:
 
-1. [Clone the Medplum Repo](/docs/contributing/clone-the-repo)
+1. [Clone the Medplum Repo](/docs/contributing/local-dev-setup) (**Note:** You can clone the main Medplum repo instead
+   of creating a fork)
 2. [Build the Project](/docs/contributing/run-the-stack)
 3. Deploy: Utilize `./scripts/deploy-bot-layer.sh` to deploy the new version.
 

@@ -4,30 +4,75 @@ sidebar_position: 1
 
 # Contributing to Medplum
 
-Medplum is an open-source project, and we love developer contributions! This section provides instructions on how to get started developing new features for Medplum.
+Medplum is an open-source project, and we love both code and non-code contributions! People with any level of experience
+can make an important impact on the project: you don't need to be a professional developer! You might have just:
 
+- **Ten minutes** to write a GitHub issue describing a bug you found or request for a feature you could use
+- **One hour** to learn and participate in one of our webinars
+- **Four hours** to author a case study showcasing how you've used Medplum
+
+This section provides instructions on how to get started contributing to the Medplum project.
 If you're looking to _use_ Medplum, check out the [App](./app) or [API](./api) docs instead.
 
-**Ready to get started? First things first, you need to [Clone the repo](./contributing/clone-the-repo).**
+## Join our online community
+
+We have several online venues where Medplum community members and team members convene, offering various ways
+to get involved with the project:
+
+1. Star the [Medplum Github repository](https://github.com/medplum/medplum)
+2. Join our [Discord channel](https://discord.gg/medplum) - and introduce yourself
+3. Subscribe to [Medplum on LinkedIn](https://www.linkedin.com/company/medplum)
+4. Follow [Medplum on Twitter](https://twitter.com/Medplum1)
+5. Subscribe to our [Youtube channel](https://www.youtube.com/channel/UCu_sS6aXEHz3GPk2NTugtJA)
+
+### Spread the word and participate
+
+Help us reach and engage people passionate about building amazing healthcare solutions!
+
+1. Let us know your thoughts on [Github Discussions](https://github.com/medplum/medplum/discussions)
+2. Share our [blog posts](/blog)
+3. Share code, posts, videos or other content in relevant online forums for example [dev.to](https://dev.to/),
+   [/r/healthIT](https://www.reddit.com/r/healthIT/), [/r/selfhosted](https://www.reddit.com/r/selfhosted/),
+   or [Hacker News](https://news.ycombinator.com)
+4. Write content for your own blog or website, and [tell us about it](mailto:hello@medplum.com)
+
+## Making a contribution
+
+There are several ways to make your first contribution to the Medplum project! The following instructions
+should help you get started.
+
+### Reporting a bug or discussing a feature idea
+
+If you found a technical bug on Medplum or have ideas for features we should implement, the [GitHub issue tracker](https://github.com/medplum/medplum/issues)
+is the best place to share your ideas.
+[Open a new issue](https://github.com/medplum/medplum/issues/new) describing the changes you'd like to see, and one of
+our team members will respond.
+
+### Writing documentation or blog content
 
-### Contributor Guidelines
+Did you learn how to do something using Medplum but it wasn't obvious on first try? Please contribute to our documentation!
 
-#### Reporting a bug or discussing a feature idea
+Our documentation is hosted on [medplum.com/docs](/docs), but it is built from [Markdown](https://www.markdownguide.org/)
+files that live in our [Github repository](https://github.com/medplum/medplum/tree/main/packages/docs/docs).
 
-If you found a technical bug on Medplum or have ideas for features we should implement, the issue tracker is the best place to share your ideas. [Click here to open a new issue](https://github.com/medplum/medplum/issues/new)!
+For relatively small changes, you can edit files directly from your web browser on [github.dev](https://github.dev/medplum/medplum/blob/main/packages/docs/docs/home.md)
+without needing to clone the repository.
 
-#### Fixing a bug or implementing a new feature
+### Fixing a bug or implementing a new feature
 
-If you find a bug on Medplum and open a PR that fixes it we'll review it as soon as possible.
+If you find a bug on Medplum and open a GitHub Pull Request that fixes it, we'll review it as soon as possible.
 
-If you want to implement a new feature, open an issue first to discuss your plans and to ensure it fits in our roadmap and plans for the app. If for some reason we don't accept your PR, you're welcome to [fork our repository](https://github.com/medplum/medplum/fork) and implement it on your own version.
+Before starting implementation of a new feature, open an issue first to discuss your plans and to ensure it fits into
+our roadmap and plans for the app. If for some reason we don't accept your PR, you're welcome to [fork our repository](https://github.com/medplum/medplum/fork)
+and implement it in your own version.
 
-<!-- ### Legal Notes -->
+**Ready to get started writing code?** First things first, you need to [clone the Medplum repository](./contributing/local-dev-setup).
 
 :::note Legal Note
 
-By making a contribution to this project, you are deemed to have accepted the [Developer Certificate of Origin](https://developercertificate.org/) (DCO).
+By submitting content to this project, you agree to adopt the [Developer Certificate of Origin (DCO)](https://developercertificate.org/) for your contributions.
 
-All conversations and communities on Medplum agree to GitHub's [Community Guidelines](https://help.github.com/en/github/site-policy/github-community-guidelines) and [Acceptable Use Policies](https://help.github.com/en/github/site-policy/github-acceptable-use-policies).
+All conversations and communities on Medplum are expected to follow GitHub's [Community Guidelines](https://help.github.com/en/github/site-policy/github-community-guidelines)
+and [Acceptable Use Policies](https://help.github.com/en/github/site-policy/github-acceptable-use-policies).
 
 :::
@@ -0,0 +1,33 @@
+---
+sidebar_position: 10
+---
+
+# Local development setup
+
+Ready to get started developing Medplum on your local machine? Great! First, you'll need to set up your own copy of the
+[Medplum repository](http://github.com/medplum/medplum) to work on, by [forking the repository](https://docs.github.com/en/get-started/quickstart/fork-a-repo)
+into your own GitHub account. **Note:** If you don't want to make changes and submit them back to the Medplum project,
+you can skip this step and proceed directly to the next step.
+
+After you've created your own fork of the Medplum repository, copy it to your local machine to work on by cloning it.
+
+## Clone the repo
+
+If you created a fork to submit Pull Requests from, you'll need to ensure you clone your fork, rather than the official
+Medplum repository. Otherwise, use `git@github.com:medplum/medplum.git` below to copy the official repository, which
+you can use to build and run the app locally.
+
+```bash
+git clone git@github.com:{YOUR GITHUB USERNAME}/medplum.git medplum
+```
+
+If you get an error saying `Permission denied` using `ssh`, you can refer to the [Github docs on setting up SSH keys](https://help.github.com/articles/error-permission-denied-publickey/).
+Alternatively, you can use the `https` method as a fallback.
+
+```sh
+git clone https://github.com/{YOUR GITHUB USERNAME}/medplum.git medplum
+```
+
+That will create a complete copy of the project source code on your local machine, including code for the Medplum Server, Medplum App, and associated libraries.
+
+In the next step, we'll build the application and run the tests.
@@ -14,7 +14,7 @@ Follow these instructions to get the complete Medplum stack running directly on
 1. **[Git](https://git-scm.com/)**
 2. **[Node.js](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm)** version 18+
 3. **[Docker](https://docs.docker.com/engine/install/)**
-4. [Clone the Medplum repo](./clone-the-repo)
+4. [Clone the Medplum repo](./local-dev-setup#clone-the-repo)
 
 ## Install
 

@@ -10,7 +10,7 @@ This document describes how the Medplum team uses the [Node.js Profiler](https:/
 
 ## Prerequisites
 
-Make sure you first [Clone the repo](/docs/contributing/clone-the-repo) and [Run the stack](/docs/contributing/run-the-stack).
+Make sure you first [Clone the repo](/docs/contributing/local-dev-setup#clone-the-repo) and [Run the stack](/docs/contributing/run-the-stack).
 
 ## Start the Profiler
 

@@ -241,7 +241,7 @@ npx medplum aws deploy-app demo
 
 **Optional:** If you intend to use Medplum Bots, you will need an [AWS Lambda Layer](https://docs.aws.amazon.com/lambda/latest/dg/gettingstarted-concepts.html#gettingstarted-concepts-layer).
 
-At present, the bot layer must be built from source. See [Clone the repo](/docs/contributing/clone-the-repo) and [Run the stack](/docs/contributing/run-the-stack) to build from source.
+At present, the bot layer must be built from source. See [Clone the repo](/docs/contributing/local-dev-setup#clone-the-repo) and [Run the stack](/docs/contributing/run-the-stack) to build from source.
 
 After you successfully build the Medplum project from source, you can use the `deploy-bot-layer.sh` script to build and deploy the Lambda Layer: