summaryrefslogtreecommitdiff
path: root/Documentation
diff options
context:
space:
mode:
authorPatrick Rudolph <patrick.rudolph@9elements.com>2018-05-28 09:36:42 +0200
committerMartin Roth <martinroth@google.com>2018-06-13 17:43:20 +0000
commit7a2a29d0e1f2ef48a2f90c190a8135da204f4d15 (patch)
tree6032127fd06c9bb18dce89afc2390a7e5116c821 /Documentation
parent16c77f72ca7ed3b68a53ecc2f9da6a2a18ba07d7 (diff)
downloadcoreboot-7a2a29d0e1f2ef48a2f90c190a8135da204f4d15.tar.xz
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>
Diffstat (limited to 'Documentation')
-rw-r--r--Documentation/getting_started/index.md1
-rw-r--r--Documentation/getting_started/writing_documentation.md74
2 files changed, 75 insertions, 0 deletions
diff --git a/Documentation/getting_started/index.md b/Documentation/getting_started/index.md
index 748d8a582a..8f2a58e1c5 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 0000000000..9a9bbf0c6f
--- /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