Update doc guidelines

- Suggest filing an issue to discuss major work before starting
 - Note that nonconforming PRs can still be submitted for content review
 - Unwrap lines
 - Minor textual fixes and improvements

basics_user/doc-guidelines.md

@@ -11,15 +11,12 @@ redirect_from:
 Documentation Guidelines
 ========================
 
-All Qubes OS documentation pages are stored as plain text files in the
+All Qubes OS documentation pages are stored as plain text files in the dedicated [qubes-doc] repository.
-dedicated [qubes-doc] repository. By cloning and regularly pulling from
+By cloning and regularly pulling from this repo, users can maintain their own up-to-date offline copy of all Qubes documentation rather than relying solely on the web.
-this repo, users can maintain their own up-to-date offline copy of all Qubes
-documentation rather than relying solely on the Web.
 
-The documentation is a community effort. Volunteers work hard trying to
+The documentation is a community effort. Volunteers work hard trying to keep everything accurate and comprehensive.
-keep everything accurate and comprehensive. If you notice a problem with the
+If you notice a problem with the documentation or some way it can be improved, please [report][issue] it!
-documentation or some way it can be improved, please [report] it! Better
+Better yet, you can [edit the documentation][contribute] yourself, both to add or improve existing content.
-yet, you can [edit the documentation][contribute] yourself, both to add or improve existing content.
 
 
 Questions, problems, and improvements
@@ -27,32 +24,35 @@ Questions, problems, and improvements
 
 If you have a question about something you read in the documentation, please send it to the appropriate [mailing list][support].
 If you see that something in the documentation should be fixed or improved, please [contribute] the change yourself.
-To report an issue with the documentation, please follow our standard [issue reporting guidelines][report].
+To report an issue with the documentation, please follow our standard [issue reporting guidelines][issue].
 (If you report an issue with the documentation, you will likely be asked to address it, unless there is a clear indication in your report that you are not willing or able to do so.)
 
 
 How to Contribute
 -----------------
 
-Editing the documentation is easy, so if you see that a change should be made,
+Editing the documentation is easy, so if you see that a change should be made, please contribute it!
-please contribute it! (As mentioned above, the documentation maintainers are
-just volunteers who have day jobs of their own, so we rely heavily on the
-community to improve the documentation.) Since Qubes is a security-oriented
-project, every documentation change will be reviewed before it's published to
-the web. This allows us to maintain quality control and protect our users.
 
-As mentioned above, we keep all the documentation in a dedicated [Git
+A few notes before we get started:
-repository][qubes-doc] hosted on [GitHub]. Thanks to the GitHub's interface, you can
-edit the documentation even if you don't know Git at all! The only thing you
-need is a GitHub account, which is free.
 
-(Note: If you're already familiar with GitHub or wish to work from the command
+ * Since Qubes is a security-oriented project, every documentation change will be reviewed before it's accepted.
-line, you can skip the rest of this section. All you need to do to contribute is
+   This allows us to maintain quality control and protect our users.
-to [fork and clone][gh-fork] the [qubes-doc] repo, make your changes, then
+ * We don't want you to spend time and effort on a contribution that we can't accept.
-[submit a pull request][gh-pull].)
+   If your contribution would take a lot of time, please [file an issue][issue] for it first so that we can make sure we're on the same page before significant works begins.
+ * Alternatively, you may already have written content that doesn't conform to these guidelines, but you'd be willing to modify it so that it does.
+   In this case, you can still submit it by following the instructions below.
+   Just make a note in your pull request that you're aware of the changes that need to be made and that you're just asking for the content to be reviewed before you spend time making those changes.
 
-Ok, let's start. Every documentation page has an "Edit this page" button. It may
+As mentioned above, we keep all the documentation in a dedicated [Git repository][qubes-doc] hosted on [GitHub].
-be on the right side (in the desktop layout):
+Thanks to GitHub's interface, you can edit the documentation even if you don't know Git at all!
+The only thing you need is a GitHub account, which is free.
+
+(**Note:** If you're already familiar with GitHub or wish to work from the command line, you can skip the rest of this section.
+All you need to do to contribute is to [fork and clone][gh-fork] the [qubes-doc] repo, make your changes, then [submit a pull request][gh-pull].)
+
+Ok, let's start.
+Every documentation page has an "Edit this page" button.
+It may be on the side (in the desktop layout):
 
 ![edit-button-desktop](/attachment/wiki/doc-edit/03-button2.png)
 
@@ -60,48 +60,43 @@ Or at the bottom (in the mobile layout):
 
 ![edit-button-mobile](/attachment/wiki/doc-edit/02-button1.png)
 
-When you click on it, you'll be prompted for your GitHub username and password
+When you click on it, you'll be prompted for your GitHub username and password (if you aren't already logged in).
-(if you aren't already logged in). You can also create an account from here.
+You can also create an account from here.
 
 ![github-sign-in](/attachment/wiki/doc-edit/04-sign-in.png)
 
-If this is your first contribution to the documentation, you need to "fork" the
+If this is your first contribution to the documentation, you need to "fork" the repository (make your own copy). It's easy --- just click the big green button on the next page.
-repository (make your own copy). It's easy --- just click the big green button
+This step is only needed the first time you make a contribution.
-on the next page. This step is only needed the first time you make a
-contribution.
 
 ![fork](/attachment/wiki/doc-edit/05-fork.png)
 
-Now you can make your modifications. You can also preview the changes to see how
+Now you can make your modifications.
-they'll be formatted by clicking the "Preview changes" tab. **Important:** If
+You can also preview the changes to see how they'll be formatted by clicking the "Preview changes" tab.
-you're making any formatting changes, please [render the site locally] to verify
+If you're making formatting changes, please [render the site locally] to verify that everything looks correct before submitting any changes.
-that everything looks correct before submitting any changes.
 
 ![edit](/attachment/wiki/doc-edit/06-edit.png)
 
-Once you're finished, describe your changes at the bottom and click "Propose file
+Once you're finished, describe your changes at the bottom and click "Propose file change".
-change".
 
 ![commit](/attachment/wiki/doc-edit/07-commit-msg.png)
 
-After that, you'll see exactly what modifications you've made. At this stage,
+After that, you'll see exactly what modifications you've made.
-those changes are still in your own copy of the documentation ("fork"). If
+At this stage, those changes are still in your own copy of the documentation ("fork").
-everything looks good, send those changes to us by pressing the "Create pull
+If everything looks good, send those changes to us by pressing the "Create pull request" button.
-request" button.
 
 ![pull-request](/attachment/wiki/doc-edit/08-review-changes.png)
 
-You will be able to adjust the pull request message and title there. In most
+You will be able to adjust the pull request message and title there.
-cases, the defaults are ok, so you can just confirm by pressing the "Create pull
+In most cases, the defaults are ok, so you can just confirm by pressing the "Create pull request" button again.
-request" button again.
 
 ![pull-request-confirm](/attachment/wiki/doc-edit/09-create-pull-request.png)
 
-That's all! We will review your changes. If everything looks good, we'll pull
+That's all!
-them into the official documentation. Otherwise, we may have some questions for
+We will review your changes.
-you, which we'll post in a comment on your pull request. (GitHub will
+If everything looks good, we'll pull them into the official documentation.
-automatically notify you if we do.) If, for some reason, we can't accept your
+Otherwise, we may have some questions for you, which we'll post in a comment on your pull request.
-pull request, we'll post a comment explaining why we can't.
+(GitHub will automatically notify you if we do.)
+If, for some reason, we can't accept your pull request, we'll post a comment explaining why we can't.
 
 ![done](/attachment/wiki/doc-edit/10-done.png)
 
@@ -115,7 +110,7 @@ To add an image to a page, use the following syntax in the main document:
 ![Image Title](/attachment/wiki/page-title/image-filename.png)
 ```
 
-Then, submit your image(s) in a separate pull request to the [qubes-attachment](https://github.com/QubesOS/qubes-attachment) repository using the same path and filename.
+Then, submit your image(s) in a separate pull request to the [qubes-attachment] repository using the same path and filename.
 
 
 Version-specific Documentation
@@ -297,7 +292,7 @@ Please try to write good commit messages, according to the
 
 [qubes-doc]: https://github.com/QubesOS/qubes-doc
 [glossary]: /doc/glossary/
-[report]: /doc/reporting-bugs/
+[issue]: /doc/reporting-bugs/
 [contribute]: #how-to-contribute
 [qubes-issues]: https://github.com/QubesOS/qubes-issues/issues
 [gh-fork]: https://guides.github.com/activities/forking/
@@ -311,4 +306,5 @@ Please try to write good commit messages, according to the
 [md]: https://daringfireball.net/projects/markdown/
 [git-commit]: /doc/coding-style/#commit-message-guidelines
 [render the site locally]: https://github.com/QubesOS/qubesos.github.io#instructions
+[qubes-attachment]: https://github.com/QubesOS/qubes-attachment