[coreboot-gerrit] Change in coreboot[master]: Documentation: Add rules for writing Documentation

[Patrick Rudolph (Code Review)]

Patrick Rudolph has uploaded this change for review. ( https://review.coreboot.org/26602


Change subject: Documentation: Add rules for writing Documentation
......................................................................

Documentation: Add rules for writing Documentation

Change-Id: Ic3808a0a10ddc8064d185e0920dcd9f60c435419
Signed-off-by: Patrick Rudolph <patrick.rudolph at 9elements.com>
---
M Documentation/index.md
A Documentation/writing_documentation.md
2 files changed, 71 insertions(+), 0 deletions(-)



  git pull ssh://review.coreboot.org:29418/coreboot refs/changes/02/26602/1

diff --git a/Documentation/index.md b/Documentation/index.md
index afe892d..1fd5c73 100644
--- a/Documentation/index.md
+++ b/Documentation/index.md
@@ -9,6 +9,7 @@
 
 * [Getting Started](getting_started/index.md)
 * [Rookie Guide](lessons/index.md)
+* [Writing Documentation](writing_documentation.md)
 * [Timestamps](timestamp.md)
 * [Dealing with Untrusted Input in SMM](technotes/2017-02-dealing-with-untrusted-input-in-smm.md)
 * [ABI data consumption](abi-data-consumption.md)
diff --git a/Documentation/writing_documentation.md b/Documentation/writing_documentation.md
new file mode 100644
index 0000000..82cb599
--- /dev/null
+++ b/Documentation/writing_documentation.md
@@ -0,0 +1,70 @@
+# 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 [shinx-autobuild] for rebuilding markdown/rst sources on the fly!
+
+## Basic and simple rules
+
+The following rules must be followed in order to get it at least reviewed on [review.coreboot.org].
+
+Documentation:
+
+1.  Must be written in **markdown** or **embedded reStructuredText** format.
+2.  Must be written in **English**.
+3.  Must be placed into **Documentation/** directory subfolder.
+4.  Must have the same directory structure as the code under **src/**.
+5.  Must be linked/included into higher markdown files if sections are used.
+6.  Must follow the [Gerrit Guidelines].
+7.  Must have all **lowercase filenames**.
+8.  Running text should have a visible width of about **72 chars**.
+9.  Must not **duplicate** documentation, but reference it instead.
+10.  Must not include the same picture in multiple markdown files.
+11.  Must not include pictures that are bigger than 500px in width.
+12.  Must include only **relevant** information.
+13.  Sholdn't go into detail, 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
+[shinx-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
+

-- 
To view, visit https://review.coreboot.org/26602
To unsubscribe, or for help writing mail filters, visit https://review.coreboot.org/settings

Gerrit-Project: coreboot
Gerrit-Branch: master
Gerrit-MessageType: newchange
Gerrit-Change-Id: Ic3808a0a10ddc8064d185e0920dcd9f60c435419
Gerrit-Change-Number: 26602
Gerrit-PatchSet: 1
Gerrit-Owner: Patrick Rudolph <patrick.rudolph at 9elements.com>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.coreboot.org/pipermail/coreboot-gerrit/attachments/20180528/c6755ee5/attachment.html>