doc-editing-doc-site-with-codespaces (#9711)

VAMobile/documentation/docs/Operations/Updating the doc site/how to update.md

@@ -5,7 +5,83 @@ sidebar_position: 2
 
 # How to update the VA Mobile doc site 
 
-_These instructions are for people who are comfortable with maintaining and troubleshooting setup on their local machine. If that's not you, please reach out to the QART tech lead for assistance._
+_If you are comfortable with maintaining and troubleshooting setup on your local machine, feel free to skip down to the section with [instructions for editing the doc site locally](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/Operations/Updating%20the%20doc%20site/how%20to%20update#updating-the-site-from-your-local-machine). If you're looking for a simpler option, use the codespaces workflow here at the top._
+
+
+## Updating the site using codespaces
+
+Follow these steps each time you want to make an update to the [VA Mobile doc site](https://department-of-veterans-affairs.github.io/va-mobile-app/) via codespaces (here's the [github documentation for codespaces](https://github.com/features/codespaces), which get you "up and coding faster with fully configured, secure cloud development environments native to GitHub.")
+
+You need:
+* A browser
+* Access to the mobile app repo
+
+### 1. Create a new branch to edit pages & make your changes  
+
+Go to [the mobile repo branches page](https://github.com/department-of-veterans-affairs/va-mobile-app/branches), and tap the green "New Branch" button near the top righthand corner of the page.
+
+Type a branch name for your branch following this pattern: doc, then your initials, then what you're updating, all separated by dashes. (Ex: doc-tkd-codespaces-addition).
+
+Keep the default source selection of develop, and tap "Create new branch".
+
+The branch that's created will appear in the middle of the page, as the first branch listed in the "Your branches" section. Tap on the blue URL branch name to be brought to the home page of your branch.
+
+Now you have a place where you can make edits to the doc site! 
+
+
+### 2. Launch a codespace for your branch 
+You can use codespaces to make changes, and see them rendered on a preview version of the doc site, so let's get a codespace running for your branch.
+
+Tap on the green "Code" dropdown button near the top righthand corner of your branch's homepage.
+* If you don't have any codespaces, you can use the big green button to make a new one. 
+* If you have a codespace (on any branch), and need a new one for this branch, you can use the "+" button to make a new one.
+* If you have a codespace for this branch that you'd like to jump back into, you can tap on the codespace name (a randomly generated phrase, like "silver guppies" or "friendly meme")
+
+This will launch a new tab in your browser, and the codespace will automatically start setting itself up. Give it a minute to fully load.
+
+Now you’re ready to start making edits to the doc site!
+
+### 3. Open the repository in the codespace, and make your changes
+Codespaces automatically run a version of VS Code (Visual Studio Code). You'll need to open up the folders where the doc site lives, to create new pages or edit existing ones.
+
+In the EXPLORER on the lefthand side, tap to expand the folders: "VAMobile", then "documentation", then "docs". The folders at this level are the sections of the doc site, so navigate from here to the md file(s) where you want to make your changes.
+
+Create or edit the files you need, then use CTRL+S to save each one.
+
+### 4. Preview the changes you've made to the doc site
+Codespaces automatically set up a preview version of the doc site when it launched, but that won't have the changes you've made. You'll need to launch a new preview doc site, to review changes you've made & saved.
+
+Select the "Terminal" tab from the tabs in the ~bottom third of your screen, then the "+" button to the far right (still in that bottom third) to open a new Terminal. Wait ~5 seconds for the new terminal to get up and running.
+- In the terminal, change to the location of the documentation site by typing (or copy-pasting) this, then tapping Enter: cd VAMobile/documentation
+- Then, launch a new doc site by typing this command, then tapping Enter: yarn start
+
+It's going to give you a warning that something is already running on port 300 (that's the preview doc site WITHOUT your changes that codespaces set up automatically). Go ahead and type "y" in response to the question about running it on another port.
+
+This opens up a new tab, and starts loading your preview version of the doc site. 
+
+The page that initially loads will always _look_ broken - don't panic! It's because codespaces is jumping you to a junk URL that doesn't exist, not an actual problem. Go ahead and use the header to navigate to the pages you've made/edited, and review them.
+
+If you want to make further changes, you can switch back to the tab with your open codespace, and then repeat steps 3 & 4 (using the 'refresh' button on your preview doc site to get new changes as you make them). 
+
+### 5. Stage, commit and sync your doc site changes
+When you're finished with your changes, you'll need to get the changes off of the codespace, and back to your branch in github.
+
+Go to the Source Control page, by tapping on the Merge icon with the blue '#' notification icon on it, along the far lefthand side of the screen.
+
+It will include a list of all of the files you've changed - review that to make sure that all of the files you expect are in there. Press the "+" button in the row with each file's name, to stage the change (staging is a fancy way to say "mark as a file you want to commit")
+
+Type a note about the changes you're making in the text box at the top of the source control area (with the preview text in it that starts with 'Message'), then tap the green "Commit" button (this commits all of the files you've staged, to the version of your branch that lives in this codespace. Yes, this is a lot of steps, but generally the point is to make it difficult to accidentally get code off of/out of your machine.)
+
+Finally, you'll tap the green "Sync" button (that has replaced the green commit button) to sync the changes from the codespace, to your branch in github. This can take a minute or longer.
+
+### 6. PR things
+
+Skip down to the shared documentation section about [how to create and merge a pull request with your changes](https://department-of-veterans-affairs.github.io/va-mobile-app/docs/Operations/Updating%20the%20doc%20site/how%20to%20update#create-a-pull-request), and follow those instructions. 
+
+Get ready for those instructions by pulling up the mobile app repo home in your browser: [https://github.com/department-of-veterans-affairs/va-mobile-app](https://github.com/department-of-veterans-affairs/va-mobile-app).
+
+
+## Updating the site from your local machine
 
 Follow these steps each time you want to make an update to the [VA Mobile doc site](https://department-of-veterans-affairs.github.io/va-mobile-app/).
 
@@ -16,6 +92,7 @@ You need:
 * A text editor (like Sublime text)
 * Terminal/Command Line
 * A browser 
+* Access to the mobile app repo
 
 ### 1. Get the latest version of the live doc site to work from  
 
@@ -127,7 +204,7 @@ The branch should get pushed up to the repository and you should then see an are
 
 
 
-**Create a pull request**  
+#### **Create a pull request**  
 
 Click the Create Pull Request button. This should open a browser window that takes you to a Pull Request template in the repository (You can also open the docsite in Github in your browser: [https://github.com/department-of-veterans-affairs/va-mobile-app](https://github.com/department-of-veterans-affairs/va-mobile-app))