From 7a2a29d0e1f2ef48a2f90c190a8135da204f4d15 Mon Sep 17 00:00:00 2001
From: Patrick Rudolph <patrick.rudolph@9elements.com>
Date: Mon, 28 May 2018 09:36:42 +0200
Subject: Documentation: Add rules for writing Documentation

Change-Id: Ic3808a0a10ddc8064d185e0920dcd9f60c435419
Signed-off-by: Patrick Rudolph <patrick.rudolph@9elements.com>
Reviewed-on: https://review.coreboot.org/26602
Tested-by: build bot (Jenkins) <no-reply@coreboot.org>
Reviewed-by: Martin Roth <martinroth@google.com>
---
 Documentation/getting_started/index.md             |  1 +
 .../getting_started/writing_documentation.md       | 74 ++++++++++++++++++++++
 2 files changed, 75 insertions(+)
 create mode 100644 Documentation/getting_started/writing_documentation.md

(limited to 'Documentation/getting_started')

diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md
index 748d8a582a76..8f2a58e1c5ff 100644
--- a/Documentation/getting_started/index.md
+++ b/Documentation/getting_started/index.md
@@ -5,3 +5,4 @@
 * [Kconfig](kconfig.md)
 * [Gerrit Guidelines](gerrit_guidelines.md)
 * [Documentation License](license.md)
+* [Writing Documentation](writing_documentation.md)
diff --git a/Documentation/getting_started/writing_documentation.md b/Documentation/getting_started/writing_documentation.md
new file mode 100644
index 000000000000..9a9bbf0c6fd3
--- /dev/null
+++ b/Documentation/getting_started/writing_documentation.md
@@ -0,0 +1,74 @@
+# coreboot documentation guidelines
+
+> Documentation is like sex: when it is good, it is very, very good;
+> and when it is bad, it is better than nothing.
+
+That said please always try to write documentation! One problem in the
+firmware development is the missing documentation. In this document
+you will get a brief introduction how to write, submit and publish
+documenation to coreboot.
+
+## Preparations
+
+coreboot uses [Sphinx] documentation tool. We prefer the markdown format
+over reStructuredText so only embedded ReST is supported. Checkout the
+[Markdown Guide] for more information.
+
+### Install Sphinx
+
+Please follow this official [guide].
+
+### Optional
+
+Install [shpinx-autobuild] for rebuilding markdown/rst sources on the fly!
+
+## Basic and simple rules
+
+The following rules should be followed in order to get it at least reviewed
+on [review.coreboot.org].
+
+Documentation:
+
+1.  Must be written in **markdown** with **embedded reStructuredText**
+    format.
+2.  Must be written in **English**.
+3.  Must be placed into **Documentation/** directory subfolder.
+4.  Should follow the same directory structure as **src/** when practical.
+5.  Must be referenced from within other markdown files
+6.  The commit must follow the [Gerrit Guidelines].
+7.  Must have all **lowercase filenames**.
+8.  Running text should have a visible width of about **72 chars**.
+9.  Should not **duplicate** documentation, but reference it instead.
+10.  Must not include the same picture in multiple markdown files.
+11.  Images should be kept small. They should be under 700px in width, as
+     the current theme doesn't allow bigger images.
+12.  Shouldn't cover implementation details; for details, the code is the
+     reference.
+
+## Markdown and Tables
+
+Under Sphinx markdown tables are not supported. Therefore you can use following
+code block to write tables in reStructuredText and embed them into the markdown:
+
+    ```eval_rst
+    +------------+------------+-----------+
+    | Header 1   | Header 2   | Header 3  |
+    +============+============+===========+
+    | body row 1 | column 2   | column 3  |
+    +------------+------------+-----------+
+    | body row 2 | Cells may span columns.|
+    +------------+------------+-----------+
+    | body row 3 | Cells may  | - Cells   |
+    +------------+ span rows. | - contain |
+    | body row 4 |            | - blocks. |
+    +------------+------------+-----------+
+    ``` #just a code block is enough
+
+[coreboot]: https://coreboot.org
+[Documentation]: https://review.coreboot.org/cgit/coreboot.git/tree/Documentation
+[shpinx-autobuild]: https://github.com/GaretJax/sphinx-autobuild
+[guide]: http://www.sphinx-doc.org/en/stable/install.html
+[Sphinx]: http://www.sphinx-doc.org/en/master/
+[Markdown Guide]: https://www.markdownguide.org/
+[Gerrit Guidelines]: https://doc.coreboot.org/gerrit_guidelines.html
+[review.coreboot.org]: https://review.coreboot.org
-- 
cgit v1.2.3