Introduction - add a reading guide for our documentation, explain a bit about the (current) scope of the docs and where to find what.

source/intro.rst

@@ -31,6 +31,60 @@ Mission Statement
 
 .. image:: ./images/OPNsense-Deciso-Screenshot.jpg
 
+
+-----------------
+Reading guide
+-----------------
+
+While reading the documentation, it's good to know how the various topics are structured, what their purpose is and how
+to find what you're looking for. Maybe even more important is what this documentation doesn't offer.
+
+If you're looking for deeper insights about networking and best practices in designing them, this might not be the best
+place to look. Most of our documents and how-to's focus on how to use functionality included in our software and/or one
+of it's plugins. Quite some books are written about networking, there are (online) courses available and wikipedia
+contains a lot of relevant articles as well. Some interesting reads include the fundamentals about the
+`OSI model <https://en.wikipedia.org/wiki/OSI_model>`__, `IP addressing <https://en.wikipedia.org/wiki/IP_address>`__,
+`routing <https://en.wikipedia.org/wiki/IP_routing>`__ and `network address translation <https://en.wikipedia.org/wiki/Network_address_translation>`__.
+Likely these resources are more suitable for learning about general network concepts.
+Although we do try to include some context in our documents, there are often assumptions made about the readers
+knowledge on (basic) networking.
+
+Like many products and projects, ours grows over time, functionality extends and changes, which sometimes makes it difficult
+to find what you need for the version your using. Although we try to keep our documentation up to date, sometimes text
+doesn't reflect reality anymore. If that's the case and you think you found an omission, don't hestitate to open
+a report using one of our templates on `GitHub <https://github.com/opnsense/docs/issues/new/choose>`__ or a pull request
+of course if you're able to.
+
+Always assume the text is intended for the latest version of our product, in time we might
+add a version selector in the documentation, but given OPNsense is a security product, we advise to keep it up to date
+anyway to protect yourself against the latests threats.
+
+The releases section contains the changelogs for all versions we published over the years, if there are remarks
+for an upgrade, this is a useful resource to collect the details.
+
+Installation and setup is all about getting you started using one of the target options available.
+
+The next sections should be quite familiair when working with OPNsense, as they reflect the options in the
+menu of the product. In case you're not yet used to OPNsense, you can always use the search input in the left corner of
+the screen to find your topic.
+
+Both community and third-party plugins have their own area available, although they eventually register into the
+same menu structure, it's good to know about possible differences between add-ons and standard functionality.
+The level of support may differ between core functionality, as also explained in the "Support options" section,
+feature requests and bugs maybe treated different as well (a lot of questions for a plugin which is being developed
+by a single person, maybe less active than a group of people improving a plugin together for example).
+
+When it it comes to building software on top of OPNsense or extending existing functionality, the development
+chapter is the one to read. It explains all about our architecture, coding style, how to hook into available facilities and
+much more.
+
+Some pointers when it comes to troubleshooting can be found in the section with the same name, it explains a bit
+about our issue workflow and some tips we collected over the years.
+
+Last but not least our documentation includes some pages around project relations, legal guidelines and
+ways to contribute to the project.
+
+
 -------------------
 
 -----------