Minor documentation improvements

src/blenderbim/docs/blenderbim.rst

@@ -1,27 +0,0 @@
-BlenderBIM
-==========
-
-BlenderBIM is an add-on to Blender that turns Blender into a powerful BIM
-authoring program, supporting IFC import, export, and data manipulation.
-
-This documentation is free software! You are free to contribute and help write
-this document.
-
-.. toctree::
-   :maxdepth: 1
-   :caption: Contents:
-
-   blenderbim/installation
-   blenderbim/developer_guide
-   blenderbim/undo_system
-   blenderbim/georeferencing
-   blenderbim/running_tests
-   blenderbim/scene
-
-
-Indices and tables
-------------------
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`

src/blenderbim/docs/devs/installation.rst

@@ -15,7 +15,7 @@ Unstable installation
 that they are typically updated every day. Simply download a daily build from
 the `Github releases page
 <https://github.com/IfcOpenShell/IfcOpenShell/releases>`__, then follow the same
-instructions as a packaged installation.
+instructions as the **Stable installation**.
 
 You will need to choose which build to download.
 

src/blenderbim/docs/index.rst

@@ -1,13 +1,18 @@
 Let's get started
 =================
 
-The BlenderBIM Add-on lets you analyse, create, and modify OpenBIM with Blender. 
+The BlenderBIM Add-on lets you analyse, create, and modify OpenBIM with Blender.
+
+.. note::
+
+   This documentation is incomplete. Would you like to help write more? `Get in touch! <https://osarch.org/chat/>`__
 
 .. toctree::
    :hidden:
    :maxdepth: 1
    :caption: For users:
 
+   users/introduction_to_bim
    users/installation
    users/exploring_an_ifc_model
    users/creating_your_first_ifc

src/blenderbim/docs/users/installation.rst

@@ -23,9 +23,13 @@ Installation
 
    `Download BlenderBIM Add-on <https://blenderbim.org/download.html>`__
 
+.. caution::
+
+   If you are not using Blender version >=3.1, please follow the **Unstable installation** instructions. :doc:`Read more <../devs/installation>`
+
 3. **Install the BlenderBIM Add-on**
 
-   Open up Blender, and access the ``Edit > Preferences`` window.
+   Open up Blender, and click on ``Edit > Preferences``.
 
    .. image:: install-blenderbim-1.png
 

src/blenderbim/docs/users/introduction_to_bim.rst

@@ -0,0 +1,59 @@
+Introduction to BIM
+===================
+
+**Building Information Modeling**, or **BIM**, is a way of digitally describing
+our built environment to computers. Aspects of our built environment that can be
+described are:
+
+- **Products**, like walls, doors, and windows
+- **Processes**, like construction or maintenance tasks, and procedures
+- **Resources**, like labour, materials, and equipment
+- **Controls**, like permits, orders, costs, or calendar availability
+- **Actors**, like occupants, clients, architects, and liable parties
+- **Groups**, like systems, inventories, or zones
+
+These objects may have lots of data and relationships. The data might be a
+classification system, physical material, associated documents, simulation
+results, construction types, or location. The data may be relevant to multiple
+disciplines, such a architecture, engineering, and construction.
+
+.. note::
+
+   BIM data is very different from a regular 3D model. In fact, geometry is
+   optional, and most data is non-geometric. This means that it is not simply a
+   3D format that you can import or export from and expect meaningful results.
+
+**Industry Foundation Classes**, or **IFC**, is an international standard for
+**BIM**. **IFC** is the most well-established open digital language for our
+built environment. Most software will be able to describe their **BIM** data
+using **IFC**.
+
+For example, **IFC** will define a wall as an object that can have a name,
+construction type, and quantities. **IFC** will also describe that a wall that
+be associated with a location, like a building storey, or have an associated
+cost item in a schedule.
+
+When you use the BlenderBIM Add-on, you will be able to view and create **BIM**
+objects and relationships using the **IFC** standard.
+
+Things you can do
+-----------------
+
+The BlenderBIM Add-on is designed to be a full BIM authoring platform. Its
+capabilities have a similar scope to other modeling platforms, costing programs,
+scheduling software, CAD packages, and simulation software. It is too numerous
+to list in full, but an example of what is possible include:
+
+- Viewing models, including spaces, properties, and relationships
+- Edit and extract attributes and properties
+- Moving objects, and changing their geometry
+- Create new objects using library elements
+- Manage classification systems, document and library references
+- Generating 2D drawings, schedules, and creating sheets
+- Investigating and editing structural analysis models
+- Connecting and managing distribution systems and ports
+- Creating construction schedules, critical path analysis, and generating sequence animations
+- Creating cost schedules, using formulas, and deriving quantities from model elements
+- Clash detection and managing issues for model coordination
+
+... and much, much more.