Documentation: add contributing information

Hello there!
I decided to create a patch from my drafts so this information
will not be lost. It still needs some attention.

It is a good idea to have the documentation in one place.
For us this means that information from these pages
https://spectrum-os.org/contributing.html, https://spectrum-os.org/participating.html
-- should be moved here https://spectrum-os.org/participating.html.

What I did particularly:

1. Added a new chapter "Contributing".
Copied here the information from here https://spectrum-os.org/contributing.html,
adapting a bit to Spectrum Docs.
2. Moved the "Building Documentation" section from "Development" to "Contributing".
3. In the "Contributing" chapter you can find the following structure:
- Communication in Spectrum (copied from https://spectrum-os.org/participating.html)
- Documentation Style Guide
- Building Documentation

I tried to fix all cross-reference links, so this new content can be used right now.
Any further updates are very welcome.

Signed-off-by: Jenni Nikolaenko <evgeniia.nikolaenko@unikie.com>
Message-Id: <20230119154307.28303-1-evgeniia.nikolaenko@unikie.com>
Reviewed-by: Alyssa Ross <hi@alyssa.is>
Signed-off-by: Alyssa Ross <hi@alyssa.is>

4 files changed, 340 insertions, 0 deletions

diff --git a/Documentation/contributing/building-documentation.adoc b/Documentation/contributing/building-documentation.adoc
new file mode 100644
index 0000000..63a3038
--- /dev/null
+++ b/Documentation/contributing/building-documentation.adoc
@@ -0,0 +1,52 @@
+= Building Documentation
+:page-parent: Contributing
+:page-nav_order: 3
+
+// SPDX-FileCopyrightText: 2022 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Make sure you have https://nixos.org/download.html[Nix] installed.
+You may also want to xref:../installation/binary-cache.adoc[configure the Spectrum
+binary cache], to avoid having to wait for dependencies to compile on
+your local system.
+
+. Get a copy of the Spectrum source code:
++
+[source,shell]
+----
+git clone https://spectrum-os.org/git/spectrum
+----
+. Enter the documentation directory:
++
+[source,shell]
+----
+cd spectrum/Documentation
+----
+. Enter the development environment:
++
+[source,shell]
+----
+nix-shell -I nixpkgs=https://spectrum-os.org/git/nixpkgs/snapshot/nixpkgs-rootfs.tar.gz
+----
+. In the development shell, do an initial build of the documentation
+site:
++
+[source,shell]
+----
+scripts/build.sh
+----
+. Run a development server for previewing changes locally:
++
+[source,shell]
+----
+jekyll serve
+----
++
+This will serve a local copy of the documentation at http://localhost:4000/.
++
+IMPORTANT: Jekyll does not handle rendering of the draw.io diagrams. If you
+modify any of those, or add new ones, run `scripts/build.sh` again to do a full
+rebuild of the site.
+
+After making changes to the documentation, see how to
+xref:../development/first-patch.adoc[send your patch] and submit the changes for review.
diff --git a/Documentation/contributing/communication.adoc b/Documentation/contributing/communication.adoc
new file mode 100644
index 0000000..bb8aeb9
--- /dev/null
+++ b/Documentation/contributing/communication.adoc
@@ -0,0 +1,89 @@
+= Communication in Spectrum
+:description: Channels, announcements and so on.
+:page-nav_order: 1
+:page-parent: Contributing
+
+// SPDX-FileCopyrightText: 2023 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+There are several places online in which announcements,
+discussion, and collaboration happen. Rather than tell
+you about them all at once, though, it is best to tell you
+which ones are relevant to you, given how you would like
+to participate (or not) in the project.
+
+Our primary methods of communication are mailing lists and IRC.
+If this is not how you are used to interacting with free
+software projects, *DON'T PANIC*.
+
+We provide instructions for how to get started, and several
+different interfaces for you to choose from depending on what workflow
+(web, mail, Atom, etc.) makes you most comfortable. Details of these
+will be explained further on, but first, you should figure out what
+communication channels are actually relevant for you.
+
+If you are interested in keeping up to date with announcements from
+Spectrum's developers, subscribe to *announce@spectrum-os.org*.
+You can discuss Spectrum and related topics in real time on IRC, or
+more long-form on spectrum-announce (_discuss@spectrum-os.org_).
+Finally, development work happens in Spectrum's
+xref:https://spectrum-os.org/git/[source repositories], and is
+discussed on spectrum-devel (_devel@spectrum-os.org_).
+
+
+== Internet Relay Chat
+
+There is a single Internet Relay Chat (IRC) channel,
+xref:ircs://irc.libera.chat:6697/spectrum[spectrum:libera.chat]
+on xref:https://libera.chat/[Libera.Chat], for all kinds of Spectrum
+discussions.You can also join through xref:https://matrix.org/[Matrix] as
+xref:https://matrix.to/#/#spectrum:libera.chat[spectrum:libera.chat].
+If you are new to IRC, you might find Matrix the easiest way to get started.
+The channel is *logged*, but the logs are not available online yet.
+
+
+== Mailing Lists
+
+If you are interested in participating in the project, or even just
+following along with it, the best thing to do is subscribe to one or
+more of the Spectrum mailing lists.
+
+If mailing lists are not your thing, that is okay! Try the
+xref:https://spectrum-os.org/lists/hyperkitty/[Web UI], which allows
+you to interact with the mailing lists much like a modern web forum.
+
+Each list has xref:https://spectrum-os.org/lists/archives/[archives]
+that can also be accessed via the web, NNTP or Atom. You are strongly
+encouraged to mirror them.
+
+[cols="1,1"]
+|===
+
+|announce@spectrum-os.org
+|This is a one-way list where announcements
+from Spectrum's developers will be posted.
+
+You can subscribe
+xref:https://spectrum-os.org/lists/mailman3/lists/announce.spectrum-os.org/[on the web],
+or by sending mail to *announce-subscribe@spectrum-os.org*.
+
+|discuss@spectrum-os.org
+|This list contains high-level discussion about the project.
+
+You can subscribe
+xref:https://spectrum-os.org/lists/mailman3/lists/discuss.spectrum-os.org/[on the web],
+or by sending mail to *discuss-subscribe@spectrum-os.org*.
+
+|devel@spectrum-os.org
+|This list is where low-level technical discussions happen,
+and where patches are sent.
+
+There is a separate guide for the Spectrum development process,
+including how patches are sent to this list and discussed.
+For more information, see
+xref:../development/working-with-patches.adoc[Working with Patches].
+
+You can subscribe
+xref:https://spectrum-os.org/lists/mailman3/lists/devel.spectrum-os.org/[on the web], or by sending mail to *devel-subscribe@spectrum-os.org*.
+
+|===
diff --git a/Documentation/contributing/index.adoc b/Documentation/contributing/index.adoc
new file mode 100644
index 0000000..4be8d69
--- /dev/null
+++ b/Documentation/contributing/index.adoc
@@ -0,0 +1,95 @@
+= Contributing
+:description: How to contribute changes to the Spectrum source repository.
+:page-nav_order: 5
+:page-has_children: true
+
+// SPDX-FileCopyrightText: 2023 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Thank you so much for your interest in contributing to Spectrum.
+Having a healthy community of people who feel empowered to work
+on the project is vital to its success.
+
+If you have any questions about the project, please
+xref:../contributing/communication.adoc[get in touch] with
+the community. We will gladly help you out!
+
+
+== Contributing Code
+
+If you are interested in contributing code to Spectrum,
+you can find the source repositories online: https://spectrum-os.org/git/.
+
+If you have made changes you would like to be included
+in the official Spectrum distribution, please send patches
+to the spectrum-devel mailing list (devel@spectrum-os.org).
+For more information, see
+xref:../development/working-with-patches.adoc[Working with Patches].
+
+Sending patches to the list is easy — you can do it with Git,
+straight from the command line. You do not have to set anything up
+in your email client, and you do not have to subscribe to the list.
+The only thing you need to do is probably to set up Git so it knows
+how to send email using your provider's SMTP server.
+These instructions https://git-send-email.io/ should be enough
+to get you going. If you are still stuck, send an email
+to *devel@spectrum-os.org* and we will help you out.
+
+Once you have Git configured correctly, sending your changes to the
+list should be as simple as something like:
+
+[listing]
+[source,shell]
+git send-email origin/master --to devel@spectrum-os.org
+
+You will be CCed on replies to your posts, so you do not even have to be
+subscribed to the mailing list if you are worried about too much traffic.
+There is also a web interface https://spectrum-os.org/lists/hyperkitty/
+that you can use to browse or even post to the mailing list.
+
+Add a Signed-off-by line to each patch you submit, to indicate your
+certification of the xref:https://spectrum-os.org/git/spectrum/tree/DCO-1.1.txt[Developer's Certificate of Origin] for that patch.
+The easiest way to do this is with `git commit's -s` flag.
+
+Do not be too afraid of getting it wrong the first couple of times.
+This might well be a new way of collaborating for you, and everybody
+understands that. Hopefully, you will soon realise just how effective
+this style of collaboration can be compared to the alternatives.
+
+== Contributing Documentation
+
+If you notice something that can be fixed or improved:
+
+. xref:https://spectrum-os.org/doc/development/first-patch.html#making-changes[Edit or add any relevant documentation].
++
+TIP: Make sure your changes are formatted correctly and consistently
+with the rest of the documentation. For information on writing guidelines,
+see xref:../contributing/writing_documentation.adoc[Documentation Style Guide].
++
+. xref:../contributing/building-documentation.adoc[Test your documentation].
+Reread what you wrote and run a spellchecker on it to make sure you did not miss anything.
+. xref:https://spectrum-os.org/doc/development/first-patch.html#submitting-changes[Submit changes].
+
+
+=== Documentation To-Do List
+
+Spectrum documentation needs are:
+
+* Reporting Bugs
+* Development conventions/style (code review, naming)
+* Integration, code philosophy
+
+The list will be updated. Improvements to the documentation are welcome!
+
+== Contributing Other Things
+
+At this stage, it is difficult to say what things would be useful
+to the project beyond code and documentation. Artwork will be
+extremely important and valuable. But, do not let that dissuade you!
+At some point, we will need all sorts of things, and we might as well
+get the work done early if people are willing to do it.
+
+If you think you have skills to offer the project beyond writing code,
+we would love to hear from you. The best thing to do is to either talk
+with us on spectrum-discuss, or in real time on IRC.
+For more information, see xref:../contributing/communication.adoc[Communication in Spectrum].
diff --git a/Documentation/contributing/writing_documentation.adoc b/Documentation/contributing/writing_documentation.adoc
new file mode 100644
index 0000000..a58da64
--- /dev/null
+++ b/Documentation/contributing/writing_documentation.adoc
@@ -0,0 +1,104 @@
+= Documentation Style Guide
+:description: Channels, announcements and so on.
+:page-nav_order: 2
+:page-parent: Contributing
+
+// SPDX-FileCopyrightText: 2023 Unikie
+// SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+Here you can find the standards we follow for writing,
+formatting, and organizing the Spectrum documentation.
+Please follow these guidelines and conventions
+when editing the documentation.
+
+We use xref:https://nixos.org/manual/nix/stable/introduction.html[Nix]
+and xref:https://github.com/just-the-docs/just-the-docs[Just the Docs]
+for building the documentation. Sources are written in AsciiDoc
+If you are new with it,
+see xref:https://docs.asciidoctor.org/asciidoc/latest/[AsciiDoc Language Documentation].
+
+If you want to test your changes,
+see xref:../contributing/building-documentation.adoc[Building Documentation].
+
+== Philosophy
+
+* 1 change = 1 patch
+* Update the documentation with the code.
+* Organize the AsciiDoc files into subdirectories.
+* Keep separate documentation for every different process
+to avoid confusion.
+* Do not assume that readers know everything you currently know.
+* Avoid jargon and acronyms, if you can.
+* Avoid multiple variations or spellings to refer to the same
+function, element, and so on.
+* Write short and useful documents. Cut out everything unnecessary,
+while also making a habit of continually improving every doc
+to suit your changing needs.
+
+
+== Document Layout
+
+* xref:https://docs.asciidoctor.org/asciidoc/latest/document/header/[Document header]:
+include your name and a revision line following the author line. Example:
+
+    = Document Title
+    :description: Some words about the content.
+    Author Name <author@example.org>
+    v1.0, 2012-02-10
+    //empty line that ends the document header
+
+* Licensing: include license information after a document header. For example:
+
+    // SPDX-FileCopyrightText: year / Name, surname / email address or the company name
+    // SPDX-License-Identifier: GFDL-1.3-no-invariants-or-later OR CC-BY-SA-4.0
+
+* Double space: the double space after the period is deliberate.
+Some people find it improves readability, and others do not like it,
+but the reason we use it in Spectrum documentation is that it allows
+text editors (Emacs) to differentiate between the ends of sentences
+and abbreviations (like "etc."), which means that you can make commands
+like "move to the next sentence" work accurately even if those
+abbreviations are used.
+
+* Character line limit:
+** Keep text hard-wrapped at 70-80 characters. (Most editors should be able
+to do this automatically.) This makes it easier to pick out specific parts
+in review, and also makes it easier to read in some editors. (It does not make a difference to the result as rendered in the web browser.)
+** Keep the text in the description attribute hard-wrapped as well. For more information, see the xref:https://docs.asciidoctor.org/asciidoc/latest/document/metadata/#description[Document Metadata] section of the Asciidoctor Docs.
+
+* Put one sentence on each line. This makes it easy to move content around, and also easy to spot (too) long sentences. For more information, see xref:https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line[AsciiDoc Recommended Practices].
+
+== Structure
+
+* Use subheading to organize information.
+* One topic per article.
+* To make accents, use xref:https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonitions].
+* Use numbered lists for actions that happen in sequence.
+* Do not use parenthesis for additional information, make a separate sentence instead.
+
+
+== Language
+
+=== Plain English
+
+Plain language is a universal language that makes information clear and better to understand.
+
+* Short, sharp sentences.
+* Use simple tenses.
+* Write in an active voice.
+* Understandable language, fewer gerunds.
+* Do not contract the words: use cannot instead of can’t.
+* Write the full name when first mentioned with the acronym in brackets.
+* Use numerals for numbers.
+* Do not use Latin words. For example:
+** perform operations, *etc.* => perform operations, *and so on*
+** *e.g.* a Microsoft SQL Server => *for example,* a Microsoft SQL Server
+** *via* the system => *through* the system
+
+=== Spelling
+
+* Use standard United States (U.S.) English. In cases where US spelling differs
+from UK spelling, use the US spelling. There is no need to fix one by
+replacing it with the other.
+* When you use filenames, URLs, and data parameters in examples, try to avoid words that are spelled differently by different groups of English speakers.
+* Use serial (Oxford) commas.