From 60b0f78e540b58d0b150f0ddf1a30785597760cb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Marek=20Marczykowski-G=C3=B3recki?= Date: Fri, 29 Jan 2016 13:40:00 +0100 Subject: [PATCH] Add ilustrated documentation contribution guide --- developers/doc-guidelines.md | 61 ++++++++++++++++++++++++++++++++++++ 1 file changed, 61 insertions(+) diff --git a/developers/doc-guidelines.md b/developers/doc-guidelines.md index ac67a077..805367e1 100644 --- a/developers/doc-guidelines.md +++ b/developers/doc-guidelines.md @@ -49,6 +49,66 @@ making contributions, please observe the following style conventions: `[ref]: http://daringfireball.net/projects/markdown/syntax#link` +Editing Qubes documentation +--------------------------- + +Editing Qubes documentation is easy, if you spot some errors, feel free to +correct it. Because Qubes OS is security-oriented project, every documentation +change will be reviewed before being visible on the main page. + +First of all, we keep documentation in git repository hosted on +[github][github]. Thanks to github interface, you can edit documentation even +if you do not know git at all. But you need a github account for that (it is +free!). + +Ok, lets start. Every documentation page have "Edit this page" button. It can +be on the right side (in desktop layout): + +![edit-button-desktop](/attachment/wiki/doc-edit/03-button2.png) + +Or at the bottom in mobile layout: + +![edit-button-mobile](/attachment/wiki/doc-edit/02-button1.png) + +When you click on it, you'll be prompted for Github username and password (if +you aren't logged in already). You can also create an account from +there. + +![github-sign-in](/attachment/wiki/doc-edit/04-sign-in.png) + +If it is your first contribution to the documentation, you need to "fork" a +repository (make your own copy). It's easy - just click that big green button +on the next page. This step is needed only for the first time. + +![fork](/attachment/wiki/doc-edit/05-fork.png) + +Then you can make your modifications. You can also preview how the changes will +be formated using "Preview changes" tab above editor. + +![edit](/attachment/wiki/doc-edit/06-edit.png) + +When you finish, describe your changes at the bottom and click "Propose file change". + +![commit](/attachment/wiki/doc-edit/07-commit-msg.png) + +After that, you'll see what exactly modification you've made. At this stage +those changes are still in your own copy of the documentation ("fork"). If +everything is ok, send those change to us back using "Create pull request" +button. + +![pull-request](/attachment/wiki/doc-edit/08-review-changes.png) + +You will be able to adjust pull request message and title there. In most cases +defaults are ok, so you can just confirm with "Create pull request" button +again. + +![pull-request-confirm](/attachment/wiki/doc-edit/09-create-pull-request.png) + + +That's all! We will review your changes and eventually pull them into Qubes +documentation. You'll get email notification about that. + +![done](/attachment/wiki/doc-edit/10-done.png) [qubes-doc]: https://github.com/QubesOS/qubes-doc [qubes]: https://github.com/QubesOS @@ -56,3 +116,4 @@ making contributions, please observe the following style conventions: [gh-pull]: https://help.github.com/articles/using-pull-requests/ [patch]: /doc/SourceCode/#sending-a-patch [lists]: https://www.qubes-os.org/doc/QubesLists/ +[github]: https://github.com/