-
Notifications
You must be signed in to change notification settings - Fork 65
Content editing for non coders
I hope the title doesn't sound pejorative. I couldn't think of any other succinct way to say it. If you need help with anything in this document, please contact one of your friendly neighborhood developers, and they'd be happy to help you out!
This page describes a pure-web workflow for updating basic content on the Design Manual, using GitHub and Prose. It does not require the use of the Terminal or the GitHub applications that are available on Windows and OS X.
The basic workflow goes like this:
- Fork the repo, or update your fork if you already have one.
- Edit the page or pages you want to update on your fork.
- Submit a pull request to get your edits merged into the official manual.
- 🎊 Party! 🎉
- Visit the official repository (aka, the "upstream") at https://github.com/cfpb/design-manual.
- Click the Fork button near the upper right of the page. (If you don't see this, make sure you're logged in to GitHub.)
- Select your personal user at the top left of the window that pops up.
If you see the message "Click here to visit the @ fork", you've already forked it before! Please see the instructions below for updating your fork.
Once the forking animation completes, you'll land on your newly-created repo.
The Design Manual gets updated fairly frequently, and by many different people. There's a good chance your fork is out of date! Before you make updates, we want to make sure your fork is up to date, to prevent any accidental conflicts in the underlying code.
What we're doing to do it actually a kind of "reverse pull request".
That is, we'll be creating a pull request from the official CFPB repository
to your fork, which you'll then accept yourself.
This is unintuitive to do in GitHub's interface, so I'll give you the shortcut.
Replace YOUR-USERNAME in the URL below with your GitHub username
(with no @ symbol) and go!
https://github.com/YOUR-USERNAME/design-manual/compare/gh-pages...cfpb:gh-pages
This will show you the a comparison of the current state of cfpb/design-manual and your fork, and it shows you what will change on your fork if you accept the pull request. Click the big green Create pull request button, give it a basic name and description, like "Update from upstream", and click the final Create pull request button.
Once the page finishes loading, click the big green Merge pull request button, and then Confirm merge. You should now be up-to-date!
Ok, now that your fork is all up-to-date, let's get to the actual editing. We'll be using a tool called Prose.
- Point your browser to http://prose.io
- Follow the steps to authorize Prose to connect to your GitHub account. This serves as your Prose login.
- Scroll down your list of repositories and open design-manual.
-
Navigate to the page you want to edit.
- Content pages are typically found in the
guides,identity, orui-toolkitfolders. - Click the name of a file to open it for editing.
- Content pages are typically found in the
-
Make your edits.
- Design Manual pages are written in a combination of Markdown and raw HTML. It should be pretty easy for you to edit, especially if you're just modifying existing content.
- Prose provides a toolbar of buttons that can help you with the most common formatting scenarios, as well as uploading images. (See below for more information on working with images.)
- If you need help with Markdown, click the question mark icon in the toolbar.
- If you're adding a new section, look for an existing section with a layout like the one you want to create. Copy that whole section, paste it where you want your new section, and replace it with your new content.
- You can preview your changes by clicking the eye icon in the right-hand toolbar.
- Note that this will not be able to preview it in the style of our Design Manual, and that some of the raw code will be incorrectly shown, but it may still be helpful for checking things like your type hierarchy, or list and link formatting.
- When done editing, commit (save) your changes to your fork by clicking the
save icon in the right-hand toolbar.
- Please provide a short description of your edits before saving. This isn't required, but it helps maintain a good Git commit log.
-
Preview in your fork of the Design Manual.
- Once you have saved your changes, after a minute or so, the changes will be visible on that page of your fork of the Design Manual.
- To get there, go to https://your-username.github.io/design-manual/.
If all looks good on your fork, it's time to submit your changes to the official manual!
The GitHub mechanism for submitting changes to another repository is called a pull request. Pull requests are a way to say "Hey, I've got these changes; will you accept them and pull them into your repository?"
So, return to the homepage of your design-manual repository: https://github.com/your-username/design-manual
You should see the description you entered when saving your changes (aka, the "commit message") at the top of the file list in a blue bar. If you don't see that, you might want to return to Prose and make sure the save completed, or seek assistance from someone else.
In the gray bar right above that, click the Pull request link. This will open up the comparison view, showing you what changes you are proposing to the upstream repository.
If a title is not pre-filled for you, enter one, and optionally enter a description. Then click Create pull request. The pull request is created an everyone watching the repository gets a notification. Now just wait for someone to review and accept it!
If a reviewer requests any changes, simply return to that page on Prose, edit some more, save again, and your pull request will automatically be updated.
Note: If you edit any other pages and save them before your open pull request is merged, your new edits will also be added to that open pull request.
_Coming soon. _