From 0b55614d3188d43cf4f492a3e06753ea869af9ca Mon Sep 17 00:00:00 2001
From: Sean Cross <sean@xobs.io>
Date: Sat, 11 Jan 2020 20:18:44 +1000
Subject: [PATCH] index: describe what a reference manual is

Signed-off-by: Sean Cross <sean@xobs.io>
---
 index.html | 21 +++++++++++++++++++++
 1 file changed, 21 insertions(+)

diff --git a/index.html b/index.html
index 03f99fd..da35ffe 100644
--- a/index.html
+++ b/index.html
@@ -129,6 +129,24 @@
                 </aside>
             </section>
 
+            <section>
+                <h2>Reference Manuals</h2>
+                <img class="fragment" data-src="img/rm-example.png">
+                <h6 class="fragment">Datasheet &ne; Reference Manual</h6>
+                <aside class="notes">
+                    How many people here know what a reference manual is?  These are documents that
+                    you hopefully get from the manufacutrer of a chip that tell you how to use it.
+                    These are the single most important part of developing a chip the normal way, as
+                    they give you all of the information on how to use a chip.  They can include
+                    everything from which memory addresses to poke to cause a pin to become an output,
+                    or how to set up the video block to output data.  Here is the first page from
+                    the reference manual for the i.MX6 used in the Novena.  You'll note that "Chapter
+                    1: Introduction" starts on page 197 -- everything before it was a table of contents
+                    -- and is almost 6000 pages long.  As an aside, reference manuals
+                    aren't datasheets -- datasheets tend to include electrical and operating
+                    information, and tend to be much shorter.
+                </aside>
+            </section>
             <section>
                 <h2>Enterprise Documentation</h2>
                 <table>
@@ -145,6 +163,9 @@
                     </tr>
                 </table>
                 <aside class="notes">
+                    So how is this monster of a document written?  I've asked several documentation
+                    writers from professional chip vendors, and they say that they have a whole team
+                    of people using a very advanced piece of realtime typesetting software.
                     Most enterprise documentation is written by a team of writers using Microsoft Word.
                     We're open source developers, and we prefer to use our own tools such as Git and CI
                     to create documentation for us.  Because we're lazy.  And prone to making mistakes.