Move contribution guides to the documentation (#41)

Move contribution guides to the documentation

source/contribute/bug-report.html.md

@@ -0,0 +1,23 @@
+---
+title: Report a bug
+summary: 'Somehting seems wrong? Maybe we can fix it together.'
+icon: alert-triangle
+time: 5 minutes
+---
+
+Plume is probably not perfect, and may contain bugs. If you see something that seems
+abnormal (unexpected behavior, display issue, a grammar mistake, etc), you can report it, so that we can fix it.
+
+## If you have a GitHub account
+
+If the issue is about Plume itself, go on [this page](https://github.com/Plume-org/Plume/issues/new?assignees=&labels=C%3A+Bug&template=bug_report.md&title=).
+Then, all you have to do is to fill the title and the description of your issue, and to validate.
+
+If your issue isn't about Plume itself, find the appropriate repository [in the list](https://github.com/Plume-org), go to the "Issues"
+tab, click the green "New issue" button, and describe your problem.
+
+## If you don't have a GitHub account
+
+If you don't have a GitHub account, and don't want to create one, you can also report your issue on Matrix.
+Join the Plume room as explained in [this guide](/contribute/discussion), and send a message explaining what is wrong.
+We will take care of creating an issue on GitHub for you.

source/contribute/code-review.html.md

@@ -0,0 +1,57 @@
+---
+title: Review the proposed changes
+icon: git-pull-request
+summary: 'Review one of the proposed pull requests.'
+time: 30 minutes
+---
+
+Some people contribute to Plume by improving it's source code. They propose changes to the
+software throught what is called "pull requests" on GitHub (thus you will need to create a GitHub
+account to follow this guide, if you don't have one yet).
+
+Here is the [list of all pull requests needing to be reviewed](https://github.com/Plume-org/Plume/pulls?q=is%3Apr+is%3Aopen+sort%3Aupdated-desc+review%3Arequired+label%3A%22S%3A+Ready+for+review%22).
+Choose one that seems interesting to you, read the discussion for context about what needs to be reviewed,
+and what was already tested, and start your review.
+
+## Test the changes
+
+Each pull request is deployed in live so that you can easily test the changes they bring.
+The URL to access the test instance is `https://pr-XXX.joinplu.me/`, where `XXX` is the number
+of the pull request (that is shown next to the title on GitHub).
+
+A list of all running test instances is also available on [pr-list.joinplu.me](https://joinplu.me). Only
+five instances may run at the same time, to avoid to overload our server. If the instance you wanted to access
+is not available, wait for the CI to run again (it will restart it), choose another pull request, or test it locally
+if you know how to do it.
+
+A good start is to go to the test instance for your pull request, and to see if everything works as expected,
+but also to try to find some corner cases that were not expected, and that may break something.
+
+Don't hesitate to try the feature on different devices too, and from different browser, especially if it changes
+the user interface.
+
+## Review the code
+
+If you know one of the programming languages used in Plume (Rust, SCSS, HTML and SQL mostly), you can also review the quality
+of the code: give advices about it's efficiency, ask for clarification if you are not sure what it does, point out potential
+bugs, etc.
+
+You can do that by going to the "Files changed" tab on the page of pull request on GitHub. Then you will be able to comment on the
+diff, as seen in this GIF:
+
+![Commenting on the diff](/images/code-review.gif)
+
+## Writing your review
+
+Once you tested the changes, you need to tell to the person who proposed the pull request what you found.
+
+The best way to do that is to go to the "Files changed" tabs on the GitHub pull request, and to click the green "Review
+changes" button, in the top right corner. Then write a comment in the box that appears, explaining what worked, and what went
+wrong. Don't hesitate to give precise information, explaining how to reproduce issues for instance. When making comments
+about someone else's work, be kind, and try to make constructive critics.
+
+Then click one of "Request changes", "Comment" or "Approve" to send your comments.
+
+It is possible that the person who opened the pull request asks for more details: the review doesn't really
+stop until the pull request is fully accepted (but you have the right to tell them you don't want to help with
+review anymore, someone else will probably take care of it).

source/contribute/development.html.md

@@ -3,9 +3,24 @@ title: Development Guide
 icon: git-merge
 summary: 'How to install Plume on your computer and make changes to the source code.
 This guide also gives you tips for making debugging and testing easier.'
-priority: 2
+time: 30 minutes
 ---
 
+Plume is mostly made in Rust. The back-end uses Rocket and Diesel. The front-end
+is in Rust too, thanks to WebAssembly. The stylesheets are written in SCSS.
+
+If you want to write some code but you don't really know where to start, you
+can try to find [an issue that interests you](https://github.com/Plume-org/Plume/issues).
+
+Then, fork Plume (if you didn't already do it), `git clone` your fork, and start a
+new branch with `git checkout -b NAME-OF-THE-BRANCH`. You can now start to work on the
+issue.
+
+Once you have something working, do `git add FILES THAT YOU CHANGED` (or `git add .` to add them all),
+and then `git commit`. Write a message explaining your changes, and do `git push origin NAME-OF-THE-BRANCH`
+to upload your work to GitHub. Open the URL that appears in the output of this last command to open
+a pull request, that we will then review, and eventually merge.
+
 ## Installing the development environment
 
 Please refer to the [installation guide](/installation). Choose to compile Plume

source/contribute/discussion.html.md

@@ -0,0 +1,34 @@
+---
+title: Join the discussion
+icon: users
+summary: 'Join our Matrix room, or our Loomio to take part to discussions about Plume, share your feedback, or ask for help.'
+time: 10 minutes
+---
+
+Discussion about Plume mostly take place on two websites: Loomio (long posts, more like a forum with decision tools) and Matrix
+(instant chat, more suited for support or feedback).
+
+Most of the discussions are in English, but if you are not fluent enough, you can speak in another language your are more comfortable
+with, maybe we speak it too, and even if we don't we will find ways to talk with you, don't worry!
+
+## Joining the Matrix room
+
+Matrix is federated chat (but it doesn't use ActivityPub 😛). If you don't have an account yet, you
+can find an instance [here](https://www.hello-matrix.net/public_servers.php) (if you don't know which one to choose, just go for matrix.org).
+Once you created an account, open [this link to join `#plume:disroot.org`](https://riot.im/app/#/room/#plume:disroot.org). And you are done!
+
+This place is the best one to give feedback or to ask for help if you encounter issues while using Plume, or while contributing for example.
+
+## Joining the Loomio
+
+Our Loomio group is hosted [on Framavox](https://framavox.org/g/WK40YHMA/plume).
+You will only be asked an email address to join it. Then, you will be able to comment
+on discussion, open new topics and vote. Feel free to take part in any topic that seems interesting.
+
+All the features that need the input from the whole community are discussed here.
+
+## Giving us feedback
+
+If you want to give us feedback about Plume, the best place is the Matrix room (you can do it in other places, but it is more likely to be missed).
+Don't hesistate to be honest when giving us feedback, and to speak about negative points as well as positive ones. As long as you aren't rude we will
+be happy to ear what you have to say about Plume.

source/contribute/documentation.html.md

@@ -0,0 +1,61 @@
+---
+title: Improve the documentation
+icon: book-open
+summary: 'Write new articles, review the current ones'
+time: 30 minutes
+---
+
+Having an accurate, understandable and complete documentation is important.
+
+Our documentation is [hosted on GitHub](https://github.com/Plume-org/docs), so you
+will need an account here if you want to edit it. You will probably need to fork it
+to create a temporary copy you have the right to edit (with the button in the top right corner).
+
+## Documenting something new
+
+If you want to start a new page from scratch, you can do it by going in the `source` folder (and eventually in
+another of the sub-folders) and by clicking the "Create new file" button (at the top of the file list).
+
+Enter its name: use a concise version of the title, with hyphens as separators between words, and the `html.md` extension.
+Then you can start writing it, using [MarkDown](https://commonmark.org/help/). Documentation should be written in English.
+
+At the top of your file, you can add some meta-data, like that:
+
+```md
+---
+title: 'The title of the page'
+summary: 'A summary of what is explained on this page.'
+icon: icon-name
+---
+```
+
+You can find a list of the icons you can use on [this page](https://feathericons.com/).
+
+## Improving the current documentation
+
+Our current documentation is probably not perfect, and proof-reading it helps a lot! However please note
+this part only applies to the English documentation, if you want to improve the documentation in another language,
+see how to [translate it](/contribute/translations).
+
+To fix the mistakes you found, you will need to fork the documentation on GitHub (as explained in the first
+paragraph of the previous part).
+
+Once it's done, choose the page you want to review, and find the corresponding file on GitHub (the URL of the page in
+the documentation and the name of the files are normally the same). Read the page to see if you can find typos, grammar
+mistakes, sentences that can be improved, etc. If you see anything that could be improved, go to GitHub and edit the file.
+
+
+## Saving your work and proposing your changes
+
+Once you finished, you can save your work. To do that, GitHub asks you to make a short summary of your changes.
+
+![The box to write a summary of your changes](/images/new-docs-page.png)
+
+Once you saved your new file, you will have to propose us the changes. To do that you will have to create a new
+pull request, that is a space where we can discuss your changes if needed, and then accept them. To do that, use the
+"Pull request" button in the file list.
+
+![The button to create a new pull request](/images/docs-pr-button.png)
+
+You can normally leave the default settings (optionally edit the title and the description if you want),
+and hit the "Create pull request" button.

source/contribute/donations.html.md

@@ -0,0 +1,14 @@
+---
+title: 'Make a donation'
+icon: dollar-sign
+summary: 'Support Plume financially.'
+time: 10 minutes
+---
+
+Plume is present [on Liberapay](https://liberapay.com/Plume). All you have to do
+to make us a donation, is to register on Liberapay and to configure a payment method,
+and then to click the "Donate" button on our page. Then just follow the instructions.
+
+It is not clear how Liberapay works since the incident they had in July 2018. However, you
+can be sure that any amount you give to Plume will be received by the contributors.
+

source/contribute/feature-request.html.md

@@ -0,0 +1,24 @@
+---
+title: Request a feature
+icon: edit
+summary: 'You have an idea of improvements for Plume? Let us know!'
+time: 10 minutes
+---
+
+If you have an idea for a new feature in Plume, we will be happy to ear what
+you have to propose.
+
+## It may need to be discussed
+
+If your feature is controversial, or not totally clear yet, the best is to open a new discussion
+[on Loomio](https://framavox.org/g/WK40YHMA/plume). If you are not sure how to do that, we have
+[a guide about it](/contribute/discussion). Give as much details as possible. Especially, explain
+which problem you are trying to solve with this new feature.
+
+## It doesn't really need to be discussed
+
+Then you can open [an issue on GitHub](https://github.com/Plume-org/Plume/issues/new?assignees=&labels=&template=feature_request.md&title=),
+if you have an account there. Just fill the information asked in the form, and click "Submit new issue".
+
+If you don't have a GitHub account, you can also suggest your feature in [the Matrix room](/contribute/discussion), and we
+will create the issue for you.

source/contribute/index.html.erb

@@ -0,0 +1,44 @@
+---
+title: Contribute to Plume
+summary: "You want to help, but you don't know how? These guides explain you how to translate Plume, hack on its source code, write documentation, etc."
+icon: heart
+priority: 2
+---
+
+<p><b>Before contributing, be sure to read and agree with our <a href="/organization/code-of-conduct">Code of conduct</a></b></p>
+
+<p>Here is a (non-exhaustive) list of how you can contribute to Plume. Some may suit you better, depending on your skills and the time you want to offer to the project</p>
+
+<div class="cards">
+<% sitemap.resources
+    .select{ |p| p.path =~ /\.html/ && p.path != "index.html" && p.url.chomp('/').split('/').size == 3 && p.path =~ /contribute\// }
+    .sort{ |a, b| a.data.title <=> b.data.title }
+    .sort{ |a, b| -(a.data.priority || 0) <=> -(b.data.priority || 0) }
+    .each do |res|
+%>
+    <article>
+        <i data-feather="<%= res.data.icon %>"></i>
+        <h2>
+            <a href="<%= res.url %>"><%= res.data.title %></a>
+        </h2>
+        <p><%= res.data.summary %></p>
+        <% if res.data.time %>
+            <small>Minimum time: <%= res.data.time %></small>
+        <% end %>
+    </article>
+<% end %>
+</div>
+
+<p>But you can also contribute differently. For instance, you could:</p>
+
+<ul>
+    <li>Talk about the project (super easy, and super helpful)</li>
+    <li>Write articles on Plume</li>
+    <li><a href="/installation">Open your own instance</a></li>
+    <li>Make a security audit</li>
+    <li>Integrate Plume with other projects. For instance you could use the <a href="/API">API</a> to make it possible to publish on Plume from your favorite writing app</li>
+</ul>
+
+<p>If you contributed to Plume, you can add yourself to the <a href="/organization/contributors">contributors page</a> if you want.</p>
+
+<p>If you ever encounter some difficulties while trying to contribute, please <a href="/contribute/discussion">tell us</a>, we will be happy to help you.</p>

source/contribute/translations.html.md

@@ -0,0 +1,75 @@
+---
+title: Translators Guide
+icon: message-circle
+summary: 'Explains how to translate Plume, joinplu.me and this documentation'
+time: 10 minutes
+---
+
+We use [Crowdin](https://crowdin.com) to translate Plume, the joinplu.me website and the documentation.
+All the original text are in English, so you will need to understand it, and to be fluent in another
+language to help us with translation.
+
+## Create a Crowdin account
+
+To translate Plume and the related projects, the first step is thus to create a Crowdin account (unless
+you already have one).
+
+You can register [here](https://crowdin.com/join). It will just ask you the typical registration information.
+You can also sign in with an account from other platforms if you want (GitHub for instance).
+
+## Join one of the Plume projects
+
+All the strings that need to be translated can be found in one of these projects:
+
+- [Plume](https://crowdin.com/project/plume): the Plume interface itself.
+- [Plume Documentation](https://crowdin.com/project/plume-docs): the documentation you are currently reading.
+- [Joinplu.me](https://crowdin.com/project/joinplume): the website introducing Plume.
+
+One these pages, you will find a list of languages. Select the one you want to translate.
+
+![The list of all currently available languages](/images/language-list.png)
+
+If your language is not in the list, [tell us](/contribute/discussion), we will add it.
+
+Once you selected a language, you will see a list of files to translate. Find one that is not
+100% complete, and open it. Something like that should load:
+
+![The Crowdin editor](/images/crowdin-editor.png)
+
+Let's see what we have here.
+
+![The Crowdin editor, but with colors for the different areas](/images/crowdin-editor-area.png)
+
+- In yellow (left sidebar), you have the list of strings to translate. Those with a green square
+are already translated, those with a red one are still to be done.
+- In blue (middle-top area), you have the actual editor, with on the top the original string, and under
+it, the box where you write translations. Sometimes, some context will be given next to the original string.
+And there is a button to save your translations too (you can do `Ctrl`/`⌘`+`Enter` to save without leaving your keyboard too).
+- In red (middle-bottom area), you have previous suggestions made by other people, and translations suggested by
+various translation services. They can sometimes be helpful, but most of the time, nothing is better than human translations.
+- And finally, in purple (right sidebar), you have an area where you can leave comments or ask questions. For instance, if
+you need more context about a string, you can ask here. We will try to answer you as fast as possible, but we are not working
+full-time on Plume, so don't worry if you don't get a reply in 5 minutes.
+
+## In-context translations
+
+Crowdin also provides a quite useful tool, called "in-context translations".
+It allows you to translate website, while browsing them, and thus having all the context to understand what needs to be done.
+
+We installed this tool for the documentation and joinplu.me (we may install it for Plume too one day, but it is a bit more
+complicated). You can go on [translate.docs.joinplu.me](https://translate.docs.joinplu.me/) and [translate.joinplu.me](https://translate.joinplu.me/)
+to use it.
+
+![An example of in-context translation](/images/crowdin-in-context.png)
+
+## Recommendations
+
+When translating Plume (and related projects), please try to follow these rules:
+
+- Be as inclusive as possible: if your langage has a form of inclusive writing, use it.
+The style of inclusive that is choosen is not very important (just try to keep coherent with what is already done).
+- Don't be too formal (but stay polite!).
+
+---
+
+That's it, you know everything you need to translate Plume! Thank you for your help!

source/index.html.erb

@@ -20,4 +20,4 @@ show_links: yes
         <p><%= res.data.summary %></p>
     </article>
 <% end %>
-</div>
+</div>

source/stylesheets/site.css.scss

@@ -191,6 +191,20 @@ aside {
 
 main > article {
   padding: 3em 0em;
+
+  img {
+    max-width: 90%;
+    display: block;
+    margin: 2em auto;
+  }
+
+  hr {
+    margin: 4em auto;
+    border: none;
+    background: $black;
+    height: 1px;
+    max-width: 5em;
+  }
 }
 
 main > article > * {