Major documentation refactoring (#4905)

src/blenderbim/docs/_static/custom.css

@@ -78,3 +78,14 @@ img.icon {
     font-size: small;
     color: #808080;
 }
+
+
+
+/* Start section cards. */
+.toc-cards {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(350px, 1fr));
+    grid-gap: 20px;
+    list-style-type: none;
+    margin-bottom: 24px;
+}

src/blenderbim/docs/contribute/writing_docs.rst

@@ -1,5 +1,5 @@
-Writing docs
-============
+Contribute to this Manual
+=========================
 
 A great way to contribute without writing code is to help writing
 documentation. Please reach out before contributing as the software is still in
@@ -15,19 +15,67 @@ All documentation is written in ReStructured Text and is available in the
 You can press the edit button on the top right on any documentation page to
 quickly edit their content.
 
-You can link to `external websites
-<https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_
+Links
+^^^^^
+
+You can link to
+
+.. code-block:: restructuredtext
+
+  `external websites
+  <https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_
+
 (note the space between the url and the link text).  You can also link to
-sections on the same page, like :ref:`devs/writing_docs:Writing technical
-documentation` or with :ref:`custom text<devs/writing_docs:writing technical
-documentation>`. Traditional references like `Writing technical documentation`_
-work too but are discouraged. You can link to other pages, like :doc:`Hello
-World<hello_world>` or sections within other pages, like
-:ref:`devs/installation:unstable installation`. We have ``autosectionlabel``
-enabled so it is not necessary to manually create labels. The depth of sections
+sections on the same page, like
+
+.. code-block:: restructuredtext
+
+  :ref:`contribute/writing_docs:Writing technical documentation`
+  
+or with
+
+.. code-block:: restructuredtext
+
+  :ref:`custom text<contribute/writing_docs:writing technical documentation>`.
+  
+Traditional references like 
+  
+.. code-block:: restructuredtext
+ 
+  `Writing technical documentation`_
+
+work too but are discouraged. You can link to other pages, like this:
+
+.. code-block:: restructuredtext
+
+  :doc:`Hello World<hello_world>`
+
+or sections within other pages, like this:
+
+.. code-block:: restructuredtext
+
+  :ref:`devs/installation:unstable installation`
+
+We have ``autosectionlabel`` enabled so it is not necessary to manually create labels. The depth of sections
 with automatic labels is set to 2, so the third level of titles
 will not get automatic labels to avoid duplication.
 
+You can still create labels manually. This way you would ensure links still works when documentation is refactored.
+
+.. code-block:: restructuredtext
+
+    .. _My label:
+
+    My Section
+    ==========
+
+    :ref:`Link to My Section <My label>`
+
+This link will work across the documentation. Make sure the label is globally unique.
+
+Images
+^^^^^^
+
 The following colours and annotation styles should be used for annotating
 images. All stroke widths are 3px with a corner radius of 3px.  Horizontal
 underlines are 5px with a corner radius of 2px. The dark green is ``39b54a`` and

src/blenderbim/docs/devs/getting_started.rst

@@ -0,0 +1,29 @@
+Getting Started
+===============
+
+BlenderBIM is an open-source project, and its development is driven by the contributions of a dedicated community of developers,
+architects, engineers, and enthusiasts. If you're interested in contributing to the project, whether by submitting bug reports,
+suggesting new features, or contributing code, your involvement is highly encouraged and appreciated.
+
+This part of the documentation covers various aspects of the BlenderBIM development process, including:
+
+- :doc:`Writing User Documentation </contribute/writing_docs>`
+- :doc:`Translations and Internationalisation </contribute/translations>`
+- Contributing Code
+    - :doc:`Installation and Setting up a Development Environment </devs/installation>`
+    - Understanding the Project Structure and Codebase
+        - :doc:`Hello, World! </devs/hello_world>`
+        - :doc:`Undo System </devs/undo_system>`
+    - :doc:`Code Style Guidelines and Best Practices </devs/code_style>`
+
+..
+    - :doc:`Submitting Pull Requests and Contributing Code </devs/contributing_code>`
+
+- :doc:`Testing and Quality Assurance </devs/running_tests>`
+    - :doc:`Running Tests </devs/running_tests>`
+- :doc:`System Support and Multiplatform Compatibility </devs/system_support>`
+- :doc:`User Experience and User Interface Guidelines </devs/ux_guidelines>`
+
+The BlenderBIM Developer Documentation is a living resource maintained by the core development team and the open-source community. It serves as a central hub for developers who want to get involved in the project, ensuring a consistent and efficient development process.
+
+By contributing to BlenderBIM, you'll not only be helping to improve and expand the capabilities of this powerful open-source BIM authoring platform but also be part of a vibrant community driving innovation in the AEC industry.

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
-usual :doc:`installation instructions</users/installation>`.
+usual :doc:`installation instructions</users/quickstart/installation>`.
 
 You will need to choose which build to download.
 

src/blenderbim/docs/index.rst

@@ -1,49 +1,196 @@
-Let's get started
-=================
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+  BlenderBIM Reference Manual
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 
-The BlenderBIM Add-on lets you analyse, create, and modify OpenBIM with Blender.
+Welcome to the manual for `BlenderBIM <https://blenderbim.org>`__,
+the free and open source BIM add-on for Blender.
 
-**Quickstart video tutorial**
+Quickstart
+==========
 
-Learn how to model a small building and create simple architectural plans, sections, 2D details, and sheet layouts in this short tutorial series.
+.. only:: builder_html and (not singlehtml)
 
-`View all tutorial videos <https://www.youtube.com/playlist?list=PLMDcOjMJYxUPHHvEHqAsOuBdSPsp6or32>`__
+   .. container:: toc-cards
 
-.. raw:: html
+      .. container:: card
 
-    <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/videoseries?list=PLMDcOjMJYxUPHHvEHqAsOuBdSPsp6or32" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+         :doc:`/users/quickstart/introduction_to_bim` (2-minute read)
+            Brief overview of BIM concepts and BlenderBIM's role.
 
-.. note::
+      .. container:: card
 
-   This documentation is incomplete. Would you like to help write more? `Get in touch! <https://osarch.org/chat/>`__
+         :doc:`/users/quickstart/installation` (5 to 10-minute process)
+            Installation guide and system requirements.
+
+      .. container:: card
+
+         :doc:`/users/quickstart/explore_model` (15-minute guide)
+            Load and navigate an IFC model.
+
+      .. container:: card
+
+         :doc:`/users/quickstart/create_model` (20-minute guide)
+            Create a simple BIM project.
+
+.. container:: global-index-toc
+
+   .. toctree::
+      :hidden:
+      :caption: Quickstart
+      :maxdepth: 1
+
+      users/quickstart/introduction_to_bim
+      users/quickstart/installation
+      users/quickstart/explore_model
+      users/quickstart/create_model
+      users/quickstart/next_steps
+
+Sections
+========
+
+.. only:: builder_html and (not singlehtml)
+
+   .. container:: toc-cards
+
+      .. container:: card
+
+         :doc:`/users/modeling/interface`
+            Guide to the BlenderBIM interface.
+
+      .. container:: card
+
+         :doc:`/users/modeling/ifc_modeling`
+            IFC modeling techniques and concepts.
+
+      .. container:: card
+
+         :doc:`/users/drawing/index`
+            2D drawing generation and annotation.
+
+      .. container:: card
+
+         :doc:`/users/advanced/index`
+            Advanced topics and large-scale modeling.
+
+      .. container:: card
+
+         :doc:`/users/tutorials/index`
+            Real-world BIM project tutorials.
+
+      .. container:: card
+
+         :doc:`/users/user_interface`
+            Detailed UI reference.
+
+      .. container:: card
+
+         :doc:`/users/appendix/index`
+            Troubleshooting and additional resources.
+
+.. container:: global-index-toc
+
+   .. toctree::
+      :hidden:
+      :caption: Sections
+      :maxdepth: 2
+
+      users/modeling/interface
+      users/modeling/ifc_modeling
+      users/drawing/index
+      users/advanced/index
+      users/tutorials/index
+      users/user_interface
+      users/appendix/index
+
+Get Involved
+============
+
+This manual is maintained largely by volunteers.
+
+Please consider joining the effort and :doc:`/contribute/writing_docs`.
+
+You can also can help with :doc:`Translations and Internationalisation </contribute/translations>`
+
+For users who want to contribute to the BlenderBIM codebase,
+please refer to the :doc:`Documentation for Developers </devs/getting_started>`.
+This part of the documentation covers various aspects of the BlenderBIM development process.
+
+You can get in touch by `joining the chat <https://osarch.org/chat/>`__.
 
 .. toctree::
    :hidden:
+   :caption: Get Involved
    :maxdepth: 1
-   :caption: For users:
 
-   users/introduction_to_bim
-   users/installation
-   users/exploring_an_ifc_model
-   users/creating_an_ifc_model
-   users/georeferencing
-   users/dealing_with_large_models
-   users/git_support
-   users/other_addons
-   users/user_interface
-   users/troubleshooting
+   contribute/writing_docs
+   contribute/translations
 
-.. toctree::
-   :hidden:
-   :maxdepth: 1
-   :caption: For developers:
 
-   devs/installation
-   devs/hello_world
-   devs/code_style
-   devs/running_tests
-   devs/writing_docs
-   devs/translations
-   devs/undo_system
-   devs/system_support
-   devs/ux_guidelines
+Developer Documentation
+=======================
+
+BlenderBIM is an open-source project, and its development is driven by the contributions of a dedicated community of developers,
+architects, engineers, and enthusiasts. If you're interested in contributing to the project, whether by submitting bug reports,
+suggesting new features, or contributing code, your involvement is highly encouraged and appreciated.
+
+
+
+.. only:: builder_html and (not singlehtml)
+
+   .. container:: toc-cards
+
+      .. container:: card
+
+         :doc:`/devs/getting_started`
+            Introduction to contributing to BlenderBIM.
+
+      .. container:: card
+
+         :doc:`/devs/installation`
+            Setting up a development environment.
+
+      .. container:: card
+
+         :doc:`/devs/hello_world`
+            Understanding the project structure.
+
+      .. container:: card
+
+         :doc:`/devs/undo_system`
+            Working with BlenderBIM's undo system.
+
+      .. container:: card
+
+         :doc:`/devs/code_style`
+            Code style guidelines and best practices.
+
+      .. container:: card
+
+         :doc:`/devs/running_tests`
+            Testing and quality assurance.
+
+      .. container:: card
+
+         :doc:`/devs/system_support`
+            Multiplatform compatibility.
+
+      .. container:: card
+
+         :doc:`/devs/ux_guidelines`
+            User experience and interface guidelines.
+
+.. container:: global-index-toc
+
+   .. toctree::
+      :hidden:
+      :caption: Developer Documentation
+      :maxdepth: 1
+
+      devs/getting_started
+      devs/installation
+      devs/hello_world
+      devs/undo_system
+      devs/code_style
+      devs/running_tests
+      devs/system_support
+      devs/ux_guidelines

src/blenderbim/docs/users/advanced/index.rst

@@ -0,0 +1,10 @@
+Advanced Use Cases
+==================
+
+Advanced topics and large-scale modeling.
+
+.. toctree::
+  :maxdepth: 1
+
+  georeferencing
+  dealing_with_large_models

src/blenderbim/docs/users/appendix/index.rst

@@ -0,0 +1,16 @@
+Appendix
+========
+
+This section provides troubleshooting, integration with other tools, and additional external resources.
+
+..
+            * Integration with Other Tools
+            * Data Exchange and Compatibility
+..
+
+.. toctree::
+   :maxdepth: 1
+
+   troubleshooting
+   git_support
+   other_addons

src/blenderbim/docs/users/appendix/troubleshooting.rst

@@ -44,10 +44,10 @@ can `report a bug <https://github.com/ifcopenshell/ifcopenshell/issues>`_ or
    enabled with factory settings.
 
    To quickly test in a clean environment, first :ref:`find your Blender
-   configuration folder<users/installation:where is the add-on installed?>`.
+   configuration folder<installation_location>`.
    Rename the folder from ``X.XX`` to something else like ``X.XX_backup``, then
    restart Blender and try follow the :doc:`installation
-   instructions<installation>` again.
+   instructions</users/quickstart/installation>` again.
 
    If this fixes your issue, consider disabling other add-ons one by one until
    you find a conflict as a next step to isolating the issue.

src/blenderbim/docs/users/drawing/index.rst

@@ -0,0 +1,119 @@
+======================
+Drawings and Documents
+======================
+
+The BlenderBIM Add-on provides powerful tools for generating 2D drawings from your 3D BIM models and adding detailed annotations.
+This section covers the process of creating various types of drawings and enhancing them with annotations.
+
+Prerequisites
+=============
+
+Before starting with 2D drafting:
+
+1. Ensure you have completed the IFC modeling section or have a completed IFC model ready.
+2. Install and update to the latest compatible version of the BlenderBIM addon as Drafting module is still in early development.
+3. Install InkScape as the drafting is heavily based on SVG files.
+
+Generating 2D Drawings
+======================
+
+Creating a Floor Plan
+---------------------
+
+
+Creating Elevations and Sections
+--------------------------------
+
+The process for creating elevations and sections is similar:
+
+
+Annotations
+===========
+
+Using Annotation Tool
+---------------------
+
+
+Annotating Plan Layout
+------------------------
+
+1. Dimension key plan elements:
+   a. Wall lengths - both external and internal
+   b. Door/window openings
+   c. Room sizes
+2. Snap dimensions to wall edges/corners.
+3. Position dimensions.
+
+
+Line Work
+=========
+
+Annotations & Tags
+==================
+
+Text Labels
+-----------
+
+Leader Lines
+------------
+
+Room Labels
+-----------
+
+Door/Window Tags
+----------------
+
+Sanitary Symbols
+================
+
+Loading Symbol Types
+--------------------
+
+
+Placing Sanitaryware
+--------------------
+
+Doors and Windows 2D outline
+----------------------------
+
+
+IFC Grids
+=========
+
+Adding Grid Lines
+-----------------
+
+
+Positioning Grids
+-----------------
+
+Displaying Grids in Drawings
+----------------------------
+
+Materials/Hatching
+==================
+
+Naming Material Layers
+----------------------
+
+Automatic Hatch Patterns
+------------------------
+
+Custom Materials
+----------------
+
+Legend
+------
+
+Next Steps
+==========
+
+After mastering these basics, you may want to explore:
+
+- Generating elevations and sections
+- Creating detail drawings
+- Setting up custom hatch patterns and line styles
+- Advanced annotation techniques
+
+Remember, effective drawings are key to communicating your design intent.
+Take time to explore the various options and develop a consistent style for your project documentation.

src/blenderbim/docs/users/introduction_to_bim.rst

@@ -1,59 +0,0 @@
-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. Examples of data might be
-classification systems, physical materials, associated documents, simulation
-results, and construction types. The data may be relevant to multiple
-disciplines, such as 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**. Most commonly, **IFC** models will be shared as a ``.ifc`` file.
-
-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.

src/blenderbim/docs/users/modeling/ifc_modeling.rst

@@ -0,0 +1,117 @@
+============
+IFC modeling
+============
+
+Understanding IFC
+=================
+
+Industry Foundation Classes (IFC) is an open, international standard for Building Information Modeling (BIM) data.
+It provides a standardized way to describe, exchange, and share information about building and construction industry data.
+
+IFC Schema
+----------
+
+The IFC schema defines a comprehensive set of consistent data representations of building information for exchange between AEC software applications.
+It covers various aspects of buildings throughout their lifecycle, from conception to demolition.
+
+Basic Spatial Objects
+---------------------
+
+IFC organizes building information in a hierarchical structure:
+
+- IfcProject
+- IfcSite
+- IfcBuilding
+- IfcBuildingStorey
+- IfcSpace
+
+buildingSMART and Standards
+---------------------------
+
+buildingSMART International (bSI) is the organization responsible for developing and maintaining the IFC standard.
+They also develop other related standards like BCF (BIM Collaboration Format) and bSDD (buildingSMART Data Dictionary).
+
+IfcOpenShell
+------------
+
+IfcOpenShell is the open-source software library used by BlenderBIM to read, write, and manipulate IFC files.
+It provides the core functionality for working with IFC data.
+
+Interoperability and Other Standards
+------------------------------------
+
+IFC is part of a broader ecosystem of open standards in the AEC industry. Other relevant standards include:
+
+- COBie (Construction Operations Building Information Exchange)
+- CityGML (City Geography Markup Language)
+- gbXML (Green Building XML)
+
+The use of open standards like IFC ensures interoperability between different software tools
+and preserves data integrity throughout the building lifecycle.
+
+Importing and Viewing IFC Models
+================================
+
+[Content about importing and viewing IFC models]
+
+Inspecting and Querying Models
+==============================
+
+[Content about inspecting and querying IFC models]
+
+Starting a New IFC Project
+==========================
+
+[Content about starting a new IFC project, including advanced options]
+
+Basic Modeling Techniques
+=========================
+
+Creating Walls
+--------------
+
+[Content about creating walls]
+
+Adding Doors and Windows
+------------------------
+
+[Content about adding doors and windows]
+
+Modeling Slabs and Roofs
+------------------------
+
+[Content about modeling slabs and roofs]
+
+Defining Rooms and Spaces
+-------------------------
+
+[Content about defining rooms and spaces]
+
+Advanced Modeling Techniques
+============================
+
+Custom Parametric Wall Types
+----------------------------
+
+[Content about creating custom parametric wall types]
+
+Modeling Furniture and Fixtures
+-------------------------------
+
+[Content about modeling furniture and fixtures]
+
+Structural Elements
+-------------------
+
+[Content about modeling structural elements]
+
+Multi-Story Buildings
+---------------------
+
+[Content about modeling multi-story buildings]
+
+Complex Structures
+------------------
+
+[Content about modeling complex structures]
+

src/blenderbim/docs/users/modeling/interface.rst

@@ -0,0 +1,92 @@
+============================
+BlenderBIM Interface Guide
+============================
+
+Introduction
+============
+
+The BlenderBIM interface extends Blender's powerful 3D environment with specialized tools for Building Information Modeling (BIM). This guide will help you navigate the BlenderBIM interface and understand its key components.
+
+BlenderBIM Workspace
+====================
+
+When you start Blender with BlenderBIM installed, you can switch to the BlenderBIM workspace
+by clicking on the BIM workspace tab at the top of the Blender window.
+
+This workspace is preconfigured with the most commonly used panels and tools for BIM workflows.
+
+
+Key Interface Elements
+======================
+
+Properties Extended
+-------------------
+
+The Properties Editor is extended to provide IFC-specific properties and settings.
+
+- Scene
+  - Project Information
+- Tool
+- Object
+
+BIM Toolbar
+-----------
+
+The BIM toolbar, typically located at the left of the 3D Viewport, contains shortcuts to frequently used BIM tools:
+
+- Explore tool
+- Create various building elements
+- Create annotations, measure distance and angles, calculate volumes, etc
+
+
+IFC Tree View
+-------------
+
+Found in the Outliner, the IFC Tree View displays the hierarchical structure of your BIM model:
+
+- Spatial Structure (Site, Building, Storey)
+- Building Elements
+- Types
+
+Customizing the Interface
+=========================
+
+BlenderBIM respects Blender's highly customizable interface. You can:
+
+- Rearrange editors and panels
+- Save custom workspace layouts
+- Create custom shortcuts for BIM operations
+
+Tips for Efficient Use
+======================
+
+1. Familiarize yourself with IFC classes and their properties.
+2. Utilize Blender's search function (F3) to quickly access BlenderBIM tools.
+
+
+Next Steps
+==========
+
+Now that you're familiar with the BlenderBIM interface, you have two main paths to continue your learning:
+
+1. Proceed with IFC Modeling:
+   If you're ready to start creating and working with BIM models, you can move on to:
+
+   - :doc:`IFC Modeling Basics </users/modeling/ifc_modeling>`
+
+2. Dive deeper into the User Interface:
+   If you want to explore more details about the BlenderBIM interface, you can refer to:
+
+   - :doc:`User Interface Reference </users/user_interface>`
+
+Choose the path that best suits your current needs and learning style. You can always come back to explore the other option later.
+
+Remember, as you become more comfortable with the interface and basic modeling, you can explore more advanced topics such as:
+
+- :doc:`Generating Documentation </users/drawing/index>`
+- :doc:`Advanced BIM Techniques </users/advanced/index>`
+
+The BlenderBIM interface is designed to integrate seamlessly with Blender while providing powerful BIM-specific functionality.
+As you progress, you'll find your BIM workflow becoming increasingly efficient and productive.
+
+

src/blenderbim/docs/users/quickstart/installation.rst

@@ -1,6 +1,11 @@
 Installation
 ============
 
+.. raw:: html
+
+    <iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/videoseries?list=PLMDcOjMJYxUPHHvEHqAsOuBdSPsp6or32" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
+
+
 1. **Download and install Blender**
 
    Blender is a free and open-source program for 3D authoring. It works on
@@ -25,7 +30,7 @@ Installation
 
 .. warning::
 
-   If you are not using Blender version >=4.1, please follow the **Unstable installation** instructions. :doc:`Read more <../devs/installation>`
+   If you are not using Blender version >=4.1, please follow the **Unstable installation** instructions. :doc:`Read more </devs/installation>`
 
 3. **Install the BlenderBIM Add-on**
 
@@ -54,7 +59,7 @@ You can enable add-ons permanently by using ``Save User Settings`` from the Addo
 
 .. seealso::
 
-    If you are a poweruser, you may be interested in the **Unstable installation** to help with testing. :doc:`Read more <../devs/installation>`
+    If you are a poweruser, you may be interested in the **Unstable installation** to help with testing. :doc:`Read more </devs/installation>`
 
 .. _where is the add-on installed:
 
@@ -84,6 +89,9 @@ installed>`.
     If you do not restart Blender, the add-on will fail to remove correctly, and you
     will need to uninstall manually.
 
+
+.. _installation_location:
+
 Where is the add-on installed?
 ------------------------------
 

src/blenderbim/docs/users/quickstart/introduction_to_bim.rst

@@ -0,0 +1,98 @@
+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. Examples of data might be
+classification systems, physical materials, associated documents, simulation
+results, and construction types. The data may be relevant to multiple
+disciplines, such as 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**. Most commonly, **IFC** models will be shared as a ``.ifc`` file.
+
+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 comprehensive and truly native
+BIM authoring platform. Its capabilities include a wide range of tasks
+and workflows typically found across various BIM and CAD software, costing
+programs, scheduling tools, and simulation applications. While not
+an exhaustive list, some of the key things you can do with BlenderBIM include:
+
+- View and explore IFC models, including spaces, properties, and relationships
+- Edit and extract attributes, properties, and metadata directly from IFC data
+- Move, rotate, and modify the geometry of objects while preserving IFC semantics
+- Create new objects using predefined library elements or custom parametric types
+- Manage classification systems, document references, and link to external libraries
+- Generate 2D drawing views like plans, sections, and elevations with customizable annotations
+- Investigate and edit structural analysis models with support for various steel profiles
+- Model and manage complex distribution systems like HVAC, plumbing, and electrical (MEP)
+- Create construction schedules, perform critical path analysis, and generate sequence animations
+- Derive quantities from model elements and create cost schedules with formulas
+- Perform clash detection and coordinate models, managing issues across disciplines
+- Integrate non-geometric data like costing, scheduling, and asset management
+
+
+Roadmap and Upcoming Features
+-----------------------------
+
+While BlenderBIM already offers a comprehensive set of BIM authoring capabilities,
+the development team and community are continuously working to expand its functionality and improve existing workflows.
+Some of the most ambitious features and enhancements on the roadmap include:
+
+Usability and Workflow Enhancements
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+- Improve user-friendliness to equip average "Joe" with capabilities to model simple projects like single family homes, making BlenderBIM a viable alternative to SketchUp.
+- Make BlenderBIM more approachable for users across different skill levels, from advanced BIM experts to architects working on smaller residential projects.
+
+Improved Drawing and Documentation Workflows
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- Continued enhancements to the drawing generation capabilities, including better dimensioning tools and support for associative dimensions linked to model geometry.
+- Advanced annotation tools with customizable tags, callouts, and the ability to define reusable annotation styles and templates.
+- Streamlined sheet layout management and improved integration with external tools like Inkscape for creating title blocks and sheet compositions.
+- Continued improvement of BlenderBIM's ability to generate comprehensive documentation sets, including drawing annotations, door schedules, wall schedules, and material tagging.
+
+Expanded Parametric Modeling Capabilities
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- Native modeling tools for complex building elements like curtain wall systems and facade panels.
+- Expanded libraries with support for country-specific and manufacturer-provided object types.
+- Enhanced support for multi-story modeling, enabling efficient duplication and coordination of building elements across various levels.
+- Expanded parametric relationships and automating more common BIM tasks to reduce manual effort and enhance productivity.
+
+Enhanced Coordination and Collaboration Features
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+- Robust model merge and coordination workflows, with detailed clash detection capabilities across different disciplines and data sources.
+- Built-in support for version control and model sharing using Git repositories, enabling better team collaboration and change tracking.
+
+
+The development roadmap is continuously updated based on user feedback, industry requirements,
+and contributions from the open-source community. By embracing an open and collaborative approach,
+BlenderBIM aims to push the boundaries of what's possible in BIM authoring,
+ensuring that it remains at the forefront of innovation in the AEC industry.

src/blenderbim/docs/users/quickstart/next_steps.rst

@@ -0,0 +1,12 @@
+Next Steps
+==========
+
+Now that you've completed the quickstart guide, you're ready to dive deeper into BlenderBIM's capabilities. Here are some suggested next steps to continue your learning journey:
+
+* :doc:`Modeling and Creating IFC Models </users/modeling/ifc_modeling>`
+   Explore advanced modeling techniques and learn how to create complex IFC models.
+
+* :doc:`Tutorials and Real-World Projects </users/tutorials/index>`
+   Apply your skills to practical, real-world BIM projects with our step-by-step tutorials.
+
+These resources will help you build upon the foundation you've established and develop more advanced skills in using BlenderBIM for your architectural and engineering projects.

src/blenderbim/docs/users/tutorials/index.rst

@@ -0,0 +1,98 @@
+=======================
+Tutorials
+=======================
+
+Project Series
+==============
+
+Step-by-step guides for real-world BIM projects.
+
+.. toctree::
+   :maxdepth: 2
+   :hidden:
+
+   project0
+   project1
+   project2
+   project3
+   project4
+   project5
+
+.. only:: builder_html and (not singlehtml)
+
+  .. container:: toc-cards
+
+    .. container:: card
+
+      :doc:`Project 0: Designing a Room <project0>`
+        * Basic walls and openings
+        * Slabs
+        * MEP
+        * Basic furniture
+        * Basic floor plan drawings
+
+    .. container:: card
+
+      :doc:`Project 1: Designing a Flat <project1>`
+        * Advanced walls and openings
+        * Profiles
+        * Rooms and spaces
+        * Furniture/fixture libraries
+        * Elevation/section drawings
+
+    .. container:: card
+
+      :doc:`Project 2: Building a Bungalow <project2>`
+        * Roof
+        * Advanced foundation
+        * Structural elements
+        * Roof openings
+        * Underground services
+        * Running services in subfloor space
+        * Drawing details
+        * Basic costing and scheduling
+
+    .. container:: card
+
+      :doc:`Project 3: Multi-Storey Single-Family Home <project3>`
+        * Templating
+        * Types
+        * Complex roofs
+        * Complex fixtures (e.g. solar panels)
+        * Complex HVAC, plumbing, electrical
+        * Basic site landscaping
+
+    .. container:: card
+
+      :doc:`Project 4: Terraced/Town Houses/Duplexes <project4>`
+        * Shared walls
+        * Shared roofs
+        * Complex landscaping
+        * Duplicating units
+        * Basic parametric floor plans
+        * Generating drawings parametrically
+        * Clash detection
+        * Coordination with other stakeholders
+
+    .. container:: card
+
+      :doc:`Project 5: Apartment Block <project5>`
+        * Multiple levels
+        * Typical floor
+        * Shared amenities and common areas
+        * Elevators
+        * Parametric services
+        * Complex structural elements
+        * Advanced exporting
+        * Merging
+        * Coordination
+        * Analysis
+        * Advanced costing and scheduling
+        * External tools
+
+Quickstart Video Tutorial
+=========================
+
+Learn how to model a small building and create simple architectural plans, sections, 2D details, and sheet layouts in this short tutorial series.
+
+`View all tutorial videos <https://www.youtube.com/playlist?list=PLMDcOjMJYxUPHHvEHqAsOuBdSPsp6or32>`__

src/blenderbim/docs/users/tutorials/project0.rst

@@ -0,0 +1,91 @@
+===========================
+Project 0: Designing a Room
+===========================
+
+In this introductory project, you'll learn the basics of using BlenderBIM to design a simple room. By the end of this tutorial, you'll have created a basic 3D model and a 2D floor plan drawing.
+
+Prerequisites
+=============
+
+- Basic knowledge of Blender interface
+- BlenderBIM Add-on installed and activated
+
+Learning Objectives
+===================
+
+- Create basic walls and openings
+- Add a floor slab
+- Incorporate basic MEP elements
+- Place basic furniture
+- Generate a simple floor plan drawing
+
+Tutorial Steps
+==============
+
+1. Setting Up the Project
+-------------------------
+
+1. Open Blender and switch to the BlenderBIM workspace
+2. Set up the project settings (units, scale, etc.)
+3. Create a new IFC project
+
+2. Creating Walls
+-----------------
+
+1. Use the "Create Wall" tool to draw the room's perimeter
+2. Adjust wall heights and thicknesses
+3. Add interior walls if needed
+
+3. Adding Openings
+------------------
+
+1. Create a door opening using the "Add Opening" tool
+2. Add a window opening
+3. Adjust opening dimensions and positions
+
+4. Creating the Floor Slab
+--------------------------
+
+1. Use the "Create Slab" tool to add a floor
+2. Adjust slab thickness and elevation
+
+5. Basic MEP Elements
+---------------------
+
+1. Add electrical outlets using IFC Electric Terminal
+2. Place a light fixture using IFC Lighting Fixture
+3. Add a simple HVAC vent using IFC Flow Terminal
+
+6. Placing Furniture
+--------------------
+
+1. Import basic furniture from the BlenderBIM library
+2. Position and rotate furniture items
+3. Adjust furniture properties if needed
+
+7. Generating a Floor Plan
+--------------------------
+
+1. Set up a plan view using the BlenderBIM drawing tools
+2. Add dimensions to the floor plan
+3. Include basic annotations and labels
+
+8. Finish
+---------
+
+1. Review IFC properties for all elements
+2. Generate a PDF of the floor plan drawing
+
+Conclusion
+==========
+
+Congratulations! You've completed your first room design using BlenderBIM. You should now have a basic understanding of creating walls, openings, slabs, and simple MEP elements, as well as generating a basic floor plan.
+
+Next Steps
+==========
+
+- Experiment with different room layouts and furniture arrangements
+- Try creating a more complex room shape
+- Explore additional MEP elements and their properties
+
+In the next project, we'll build upon these skills to design a complete flat, introducing more advanced concepts and techniques.

src/blenderbim/docs/users/tutorials/project1.rst

@@ -0,0 +1,114 @@
+===========================
+Project 1: Designing a Flat
+===========================
+
+Building on the skills from Project 0, this tutorial will guide you through designing a complete flat using BlenderBIM. You'll learn more advanced techniques for creating walls and openings, working with profiles, defining rooms and spaces, and generating more detailed drawings.
+
+Prerequisites
+=============
+
+- Completion of Project 0: Designing a Room
+- Familiarity with basic BlenderBIM tools and interface
+
+Learning Objectives
+===================
+
+- Create advanced walls and openings
+- Work with profiles for custom architectural elements
+- Define and manage rooms and spaces
+- Use furniture and fixture libraries
+- Generate elevation and section drawings
+
+Tutorial Steps
+==============
+
+1. Project Setup
+----------------
+
+1. Create a new IFC project
+2. Set up project parameters (units, scale, geolocation)
+3. Import any necessary custom libraries or templates
+
+2. Advanced Wall Creation
+-------------------------
+
+1. Use the "Create Wall" tool to layout the flat's exterior walls
+2. Add interior walls with varying thicknesses
+3. Create curved walls for architectural interest
+4. Apply different materials to walls
+
+3. Complex Openings
+-------------------
+
+1. Add various door types (sliding, pocket, double)
+2. Create windows with different styles (casement, sliding, bay)
+3. Design a balcony door with sidelight windows
+4. Add skylights or clerestory windows if applicable
+
+4. Working with Profiles
+------------------------
+
+1. Create a custom cornice profile
+2. Design a baseboard profile
+3. Apply profiles to walls and openings
+4. Create a custom handrail profile for stairs or balcony
+
+5. Defining Rooms and Spaces
+----------------------------
+
+1. Use the "Create Space" tool to define individual rooms
+2. Set room names and numbers
+3. Calculate and display room areas
+4. Assign room finishes (flooring, wall finishes, ceiling)
+
+6. Using Furniture and Fixture Libraries
+----------------------------------------
+
+1. Import furniture from BlenderBIM libraries
+2. Place and arrange furniture in each room
+3. Add plumbing fixtures (sinks, toilets, bathtub/shower)
+4. Include kitchen appliances and cabinetry
+
+7. MEP Systems
+--------------
+
+1. Design basic electrical layout (outlets, switches, lighting)
+2. Add HVAC elements (vents, radiators)
+3. Create a simple plumbing system
+
+8. Stairs and Railings
+----------------------
+
+1. Design an internal staircase (if multi-level flat)
+2. Add railings to stairs and balcony
+3. Create landings and adjust riser/tread dimensions
+
+9. Generating Drawings
+----------------------
+
+1. Create floor plans for each level
+2. Generate elevation drawings (front, back, sides)
+3. Produce section drawings through key areas
+4. Add dimensions, annotations, and labels to all drawings
+
+10. Final Touches and Export
+----------------------------
+
+1. Review and adjust IFC properties for all elements
+2. Create a basic materials and finishes schedule
+3. Generate a set of PDF drawings
+
+Conclusion
+==========
+
+Congratulations on completing the flat design! You've now expanded your skills to include more complex architectural elements, space planning, and detailed drawing generation.
+
+Next Steps
+==========
+
+- Experiment with different flat layouts and styles
+- Try creating custom families for unique furniture or fixtures
+- Explore more advanced MEP systems
+- Learn about creating custom annotation styles for drawings
+
+In the next project, we'll scale up to design a full bungalow, introducing concepts like roof design, foundations, and basic structural elements.

src/blenderbim/docs/users/tutorials/project2.rst

@@ -0,0 +1,147 @@
+==============================
+Project 2: Building a Bungalow
+==============================
+
+In this project, we'll take your BlenderBIM skills to the next level by designing a complete bungalow.
+You'll learn about roof design, advanced foundations, structural elements, and more complex MEP systems.
+We'll also introduce basic costing and scheduling concepts.
+
+Prerequisites
+=============
+
+- Completion of Project 1: Designing a Flat
+- Good understanding of BlenderBIM's basic and intermediate features
+
+Learning Objectives
+===================
+
+- Design and model a complete roof structure
+- Create advanced foundations
+- Incorporate structural elements
+- Model roof openings and dormers
+- Design underground services
+- Create running services in subfloor space
+- Generate detailed drawings
+- Introduce basic costing and scheduling
+
+Tutorial Steps
+==============
+
+1. Project Initialization
+-------------------------
+
+1. Set up a new IFC project for the bungalow
+2. Define project parameters (site conditions, climate zone, etc.)
+3. Create a basic site plan
+
+2. Advanced Foundation Design
+-----------------------------
+
+1. Model foundation walls and footings
+2. Create a slab-on-grade foundation
+3. Add insulation and damp-proofing elements
+4. Model foundation vents and access points
+
+3. Structural Elements
+----------------------
+
+1. Add load-bearing walls
+2. Incorporate steel or wooden beams and columns
+3. Model floor joists and subfloor
+4. Create lintels for openings
+
+4. Roof Design
+--------------
+
+1. Choose a roof style (gable, hip, combination)
+2. Model roof trusses or rafters
+3. Add roof sheathing and finishing materials
+4. Create eaves, fascias, and soffits
+
+5. Roof Openings and Dormers
+----------------------------
+
+1. Design and place skylights
+2. Create chimney openings
+3. Model dormers (if applicable)
+4. Add roof vents
+
+6. Underground Services
+-----------------------
+
+1. Design and model a septic system or sewer connection
+2. Create water supply lines
+3. Add electrical service entrance
+4. Model gas lines (if applicable)
+
+7. Subfloor Services
+--------------------
+
+1. Design HVAC ductwork in the subfloor space
+2. Create plumbing runs
+3. Model electrical conduits
+4. Add insulation between floor joists
+
+8. Interior and Exterior Finishes
+---------------------------------
+
+1. Apply wall finishes (drywall, plaster, etc.)
+2. Add flooring materials
+3. Model ceiling finishes
+4. Create exterior cladding (siding, brick, stone)
+
+9. MEP Systems
+--------------
+
+1. Design a more complex electrical system
+2. Create a comprehensive HVAC layout
+3. Model a complete plumbing system
+4. Add smart home or security system elements
+
+10. Detailed Drawings
+---------------------
+
+1. Generate foundation plans
+2. Create framing plans (floor and roof)
+3. Produce detailed sections showing construction assemblies
+4. Design detail drawings for complex junctions (roof-wall, foundation-wall)
+
+11. Basic Costing
+-----------------
+
+1. Assign basic cost data to building elements
+2. Create a simple bill of quantities
+3. Generate a basic cost estimate
+
+12. Introduction to Scheduling
+------------------------------
+
+1. Break down the project into basic construction phases
+2. Assign durations to major tasks
+3. Create a simple Gantt chart
+
+13. Final Steps and Export
+--------------------------
+
+1. Review and refine all IFC properties
+2. Generate a complete set of drawings
+3. Create a basic project manual with drawings, cost estimate, and schedule
+
+Conclusion
+==========
+
+Congratulations on designing a complete bungalow!
+You've now expanded your skills to include more complex architectural and engineering concepts,
+as well as basic project management tools.
+
+Next Steps
+==========
+
+- Experiment with different bungalow styles and layouts
+- Dive deeper into structural engineering concepts
+- Explore more advanced MEP system designs
+- Learn about energy modeling and sustainability features
+- Develop more detailed cost estimates and construction schedules
+
+In the next project, we'll scale up to a multi-story single-family home, introducing concepts like complex roofs,
+advanced MEP systems, and basic site landscaping.

src/blenderbim/docs/users/tutorials/project3.rst

@@ -0,0 +1,153 @@
+==========================================
+Project 3: Multi-Storey Single-Family Home
+==========================================
+
+In this project, we'll design a multi-storey single-family home using BlenderBIM.
+This tutorial will introduce more advanced concepts such as templating, complex roofs, and sophisticated MEP systems.
+We'll also touch on basic site landscaping.
+
+Prerequisites
+=============
+
+- Completion of Project 2: Building a Bungalow
+- Strong understanding of BlenderBIM's features and IFC concepts
+
+Learning Objectives
+===================
+
+- Use templating for efficient design
+- Work with types for consistent elements
+- Design complex roof structures
+- Model complex fixtures (e.g., solar panels)
+- Create advanced HVAC, plumbing, and electrical systems
+- Implement basic site landscaping
+
+Tutorial Steps
+==============
+
+1. Project Setup and Templating
+-------------------------------
+
+1. Create a new IFC project for the multi-storey home
+2. Set up project templates for walls, floors, and other common elements
+3. Establish a grid system for the building
+
+2. Building Shell Design
+------------------------
+
+1. Create the ground floor layout using templates
+2. Design upper floors, incorporating different room layouts
+3. Add staircases and elevator shafts
+4. Model exterior walls with varied materials and insulation layers
+
+3. Complex Roof Design
+----------------------
+
+1. Design a complex roof structure (e.g., combination of hip and gable)
+2. Create dormers and other roof features
+3. Model roof trusses or rafters for the complex shape
+4. Add gutters and downspouts
+
+4. Advanced Window and Door Types
+---------------------------------
+
+1. Create custom window types (e.g., bay windows, corner windows)
+2. Design specialty doors (e.g., bifold patio doors, garage doors)
+3. Implement window and door schedules
+
+5. Complex Fixtures and Fittings
+--------------------------------
+
+1. Design and place solar panels on the roof
+2. Create a complex kitchen layout with custom cabinetry
+3. Model built-in furniture and storage solutions
+4. Add smart home fixtures (e.g., automated blinds, security cameras)
+
+6. Advanced HVAC System
+-----------------------
+
+1. Design a multi-zone HVAC system
+2. Create a heat recovery ventilation system
+3. Model ductwork and vents across multiple floors
+4. Implement a radiant floor heating system
+
+7. Complex Plumbing System
+--------------------------
+
+1. Design a multi-floor plumbing system
+2. Create a greywater recycling system
+3. Model hot water recirculation
+4. Design an outdoor irrigation system
+
+8. Advanced Electrical System
+-----------------------------
+
+1. Create a comprehensive electrical plan for all floors
+2. Design a smart electrical panel
+3. Implement a home automation system
+4. Add an electric vehicle charging station
+
+9. Structural Considerations
+----------------------------
+
+1. Model load-bearing walls and columns
+2. Create floor and roof structural systems
+3. Design foundation systems for the multi-storey structure
+4. Implement seismic reinforcement elements (if applicable)
+
+10. Energy Efficiency Features
+------------------------------
+
+1. Add high-performance insulation to walls and roof
+2. Implement triple-pane windows
+3. Design shading devices for sun control
+4. Create a green roof section
+
+11. Basic Site Landscaping
+--------------------------
+
+1. Model basic terrain around the house
+2. Add driveways and walkways
+3. Create simple vegetation (trees, shrubs, grass)
+4. Design a basic water feature or pool
+
+12. Advanced Drawings and Documentation
+---------------------------------------
+
+1. Generate multi-floor plans
+2. Create detailed section drawings showing multi-storey construction
+3. Produce roof plans and elevations
+4. Design construction detail drawings for complex junctions
+
+13. IFC Data Management
+-----------------------
+
+1. Ensure proper classification of all building elements
+2. Assign detailed IFC properties to elements
+3. Create property sets for energy analysis
+4. Implement space boundaries for energy simulation
+
+14. Final Steps and Export
+--------------------------
+
+1. Review and refine the entire model
+2. Generate a complete set of drawings and schedules
+3. Create a basic BIM execution plan
+
+Conclusion
+==========
+
+Congratulations on designing a complex multi-storey single-family home!
+You've now mastered advanced architectural modeling techniques, complex building systems, and basic site design.
+
+Next Steps
+==========
+
+- Explore more advanced site and landscape design
+- Dive into detailed energy modeling and analysis
+- Learn about parametric design for custom building components
+- Investigate BIM collaboration workflows with other disciplines
+- Study more advanced structural analysis integration
+
+In the next project, we'll tackle a more complex residential development with multiple units,
+introducing concepts like shared walls, parametric design, and clash detection.

src/blenderbim/docs/users/tutorials/project4.rst

@@ -0,0 +1,151 @@
+========================================
+Project 4: Terraced/Town Houses/Duplexes
+========================================
+
+In this project, we'll design a row of terraced houses, town houses, or duplexes using BlenderBIM.
+This tutorial will introduce concepts such as shared walls, duplicating units, parametric design,
+and collaboration with other stakeholders.
+
+Prerequisites
+=============
+
+- Completion of Project 3: Multi-Storey Single-Family Home
+- Advanced understanding of BlenderBIM and IFC concepts
+
+Learning Objectives
+===================
+
+- Design shared walls between units
+- Create shared roof structures
+- Implement complex landscaping for multiple units
+- Use parametric design for efficient unit creation
+- Generate drawings parametrically
+- Perform basic clash detection
+- Practice coordination with other stakeholders
+
+Tutorial Steps
+==============
+
+1. Project Setup and Master Planning
+------------------------------------
+
+1. Create a new IFC project for the terraced/town house development
+2. Develop a site plan for multiple units
+3. Establish a naming convention for units and shared elements
+
+2. Designing the Base Unit
+--------------------------
+
+1. Create a parametric model for a single unit
+2. Design shared walls with appropriate fire ratings
+3. Model floors and ceilings, considering sound insulation
+4. Create a basic roof structure that can be shared or individual
+
+3. Shared Walls and Structures
+------------------------------
+
+1. Implement shared walls between units
+2. Design party wall details for fire and sound separation
+3. Create shared foundation elements
+4. Model shared roof structures
+
+5. Duplicating and Modifying Units
+----------------------------------
+
+1. Duplicate the base unit
+2. Implement parametric variations for end units and corner units
+3. Create mirrored units for variety
+4. Adjust units for site topography
+
+6. Complex Landscaping
+----------------------
+
+1. Design shared green spaces
+2. Create individual garden areas
+3. Model driveways and shared parking areas
+4. Implement sustainable drainage systems
+
+7. Parametric Floor Plans
+-------------------------
+
+1. Develop a parametric system for generating floor plans
+2. Create options for different internal layouts
+3. Implement rules for automatic room labeling and area calculations
+
+8. MEP Systems for Multiple Units
+---------------------------------
+
+1. Design individual and shared MEP systems
+2. Create utility connection points for each unit
+3. Model shared building services (e.g., central heating plant)
+4. Implement smart metering systems
+
+9. Generating Parametric Drawings
+---------------------------------
+
+1. Set up a system for automatic drawing generation
+2. Create templates for plans, sections, and elevations
+3. Implement automatic dimensioning and annotation
+4. Generate schedules for doors, windows, and finishes
+
+10. Clash Detection
+-------------------
+
+1. Perform clash detection between architectural and MEP elements
+2. Check for clashes between units
+3. Verify clearances for accessibility and code compliance
+4. Generate clash reports
+
+11. Coordination with Other Stakeholders
+----------------------------------------
+
+1. Set up a collaborative BIM environment
+2. Create discipline-specific models (structural, MEP)
+3. Implement a change management process
+4. Use BCF (BIM Collaboration Format) for issue tracking
+
+12. Quantity Takeoff and Cost Estimation
+----------------------------------------
+
+1. Generate quantity takeoffs for materials and elements
+2. Create cost estimates based on unit types
+3. Implement cost comparison between different unit configurations
+
+13. Construction Sequencing
+---------------------------
+
+1. Develop a basic construction sequence for the development
+2. Create 4D simulations of the construction process
+3. Identify critical path activities
+
+14. Sustainability and Energy Analysis
+--------------------------------------
+
+1. Perform basic energy analysis for different unit types
+2. Implement sustainability features (e.g., green roofs, solar panels)
+3. Calculate and compare energy ratings for units
+
+15. Documentation and Deliverables
+----------------------------------
+
+1. Generate a complete set of drawings for the development
+2. Create marketing materials (e.g., 3D renderings, virtual tours)
+3. Prepare a BIM execution plan for the project
+
+Conclusion
+==========
+
+Congratulations on designing a complex multi-unit residential development!
+You've now mastered advanced concepts in parametric design, collaboration, and project coordination.
+
+Next Steps
+==========
+
+- Explore more advanced parametric design techniques
+- Dive deeper into BIM collaboration and project management
+- Learn about BIM for facilities management and handover
+- Investigate integration with GIS for larger site planning
+- Study algorithms for optimizing unit layouts and site arrangement
+
+In the final project, we'll scale up to an apartment block, introducing concepts like vertical transportation,
+advanced MEP systems, and complex structural analysis.

src/blenderbim/docs/users/tutorials/project5.rst

@@ -0,0 +1,184 @@
+==========================
+Project 5: Apartment Block
+==========================
+
+In this final project, we'll design a complex apartment block using BlenderBIM.
+This tutorial will introduce advanced concepts such as multi-level design, vertical transportation, parametric services,
+complex structural elements, and advanced project management techniques.
+
+Prerequisites
+=============
+
+- Completion of Project 4: Terraced/Town Houses/Duplexes
+- Expert-level understanding of BlenderBIM and IFC concepts
+- Basic knowledge of structural and MEP engineering principles
+
+Learning Objectives
+===================
+
+- Design a multi-level apartment building
+- Create a typical floor with multiple apartment units
+- Model shared amenities and common areas
+- Implement vertical transportation systems (elevators, stairs)
+- Design parametric MEP services
+- Model complex structural elements
+- Perform advanced exporting, merging, and coordination
+- Conduct basic structural and energy analysis
+- Implement advanced costing and scheduling techniques
+- Integrate with external tools for specialized analyses
+
+Tutorial Steps
+==============
+
+1. Project Initialization and Master Planning
+---------------------------------------------
+
+1. Set up a new IFC project for the apartment block
+2. Develop a comprehensive site plan
+3. Establish a building program (number of units, amenities, etc.)
+4. Create a basic massing model
+
+2. Designing the Typical Floor
+------------------------------
+
+1. Design a typical floor layout with multiple apartment units
+2. Create parametric apartment types (studio, 1-bed, 2-bed, etc.)
+3. Implement circulation areas (corridors, lobbies)
+4. Design shared utility spaces (trash rooms, electrical closets)
+
+3. Vertical Circulation and Transportation
+------------------------------------------
+
+1. Model elevator shafts and machine rooms
+2. Design main and emergency staircases
+3. Implement fire escape routes and strategies
+4. Create mail rooms and package delivery systems
+
+4. Ground Floor and Amenities
+-----------------------------
+
+1. Design the building lobby and reception area
+2. Create shared amenities (gym, lounge, coworking space)
+3. Model retail spaces (if applicable)
+4. Design underground parking levels
+
+5. Rooftop and Mechanical Penthouse
+-----------------------------------
+
+1. Create a rooftop terrace or garden
+2. Design the mechanical penthouse
+3. Implement green roof systems or solar panel arrays
+4. Model communication equipment (antennas, satellite dishes)
+
+6. Complex Structural System
+----------------------------
+
+1. Design the building's primary structure (columns, beams, shear walls)
+2. Model floor slabs and transfer structures
+3. Implement foundation systems (piles, raft foundation)
+4. Create expansion joints and seismic design elements
+
+7. Advanced MEP Systems
+-----------------------
+
+1. Design a central HVAC system with vertical distribution
+2. Create a multi-level plumbing system with pressure zones
+3. Implement electrical systems including emergency power
+4. Model fire protection systems (sprinklers, standpipes)
+5. Design smart building systems and BMS integration
+
+8. Facade Design and Modeling
+-----------------------------
+
+1. Create a parametric curtain wall system
+2. Design balconies and terraces
+3. Implement shading devices and architectural features
+4. Model facade access systems for maintenance
+
+9. Parametric Unit Fit-Out
+--------------------------
+
+1. Develop parametric kitchen and bathroom layouts
+2. Create furniture packages for different unit types
+3. Implement finish schedules and material specifications
+4. Design storage solutions and built-in elements
+
+10. Advanced Drawing Generation
+-------------------------------
+
+1. Create a comprehensive set of floor plans
+2. Generate detailed sections and elevations
+3. Produce construction detail drawings for complex assemblies
+4. Develop 3D views and renderings for marketing purposes
+
+11. Quantity Takeoff and Cost Estimation
+----------------------------------------
+
+1. Perform detailed quantity takeoffs for all building elements
+2. Develop a comprehensive cost estimate
+3. Implement cost-loaded scheduling
+
+12. Construction Sequencing and 4D Modeling
+-------------------------------------------
+
+1. Develop a detailed construction schedule
+2. Create a 4D model linking schedule to building elements
+3. Simulate the construction process
+
+13. Sustainability and Energy Analysis
+--------------------------------------
+
+1. Perform detailed energy modeling for the entire building
+2. Analyze daylighting and solar exposure
+3. Calculate and optimize the building's carbon footprint
+
+14. Coordination and Clash Detection
+------------------------------------
+
+1. Merge architectural, structural, and MEP models
+2. Perform comprehensive clash detection
+3. Generate clash reports and resolution strategies
+4. Implement a change management system
+
+15. Integration with External Tools
+-----------------------------------
+
+1. Export models for specialized structural analysis
+2. Integrate with energy simulation software
+3. Use computational fluid dynamics for wind analysis
+4. Implement acoustic modeling for unit sound isolation
+
+16. Facility Management Preparation
+-----------------------------------
+
+1. Develop a comprehensive asset register
+2. Create maintenance schedules for building systems
+3. Implement space management strategies
+4. Prepare handover documentation for facility managers
+
+17. Final Documentation and Deliverables
+----------------------------------------
+
+1. Compile a complete set of construction documents
+2. Create a BIM execution plan for the entire project lifecycle
+3. Develop user manuals and operational guidelines
+4. Prepare final IFC models for handover
+
+Conclusion
+==========
+
+Congratulations on completing the design of a complex apartment block!
+You've now mastered advanced concepts in multi-level building design, complex systems integration, and project lifecycle management using BlenderBIM.
+
+Next Steps
+==========
+
+- Explore specialized areas like urban planning and infrastructure modeling
+- Dive into advanced computational design and generative architecture
+- Study integration of BIM with emerging technologies (IoT, AI, VR/AR)
+- Investigate BIM for building performance optimization and predictive maintenance
+- Learn about BIM implementation strategies for large organizations
+
+This project concludes our tutorial series.
+You now have a comprehensive understanding of using BlenderBIM for various scales of architectural projects,
+from single rooms to complex multi-unit buildings.

src/blenderbim/docs/users/user_interface.rst

@@ -1,10 +1,16 @@
-User interface
-==============
+User Interface Reference
+========================
 
 This section covers the general user interface of BlenderBIM. User interface documentation does not cover any specific use case but provides a general reference of BlenderBIM UI.
 
 The documentation doesn't cover Blender UI, but makes references to `Blender documentation <https://docs.blender.org/manual/en/latest/interface/index.html>`__ where appropriate.
 
+.. * Navigating the Project Browser and Outliner
+.. * Using the Property Panels
+.. * Toolbars and Menus
+.. * Customizing the Interface
+.. * Keyboard Shortcuts and Preferences
+
 .. toctree::
    :hidden:
    :maxdepth: 1

src/blenderbim/docs/users/user_interface/property_editor/scene_editor/project_overview/project_info.rst

@@ -62,9 +62,15 @@ Fields
 **Template**
   Choose between starting a completely blank project with no objects, or with preloaded object assets (such as wall types, beam types, etc) that you can use immediately.
 
-  The blank project is recommended for users who want to curate assets, whereas the IFC4 Demo Template is recommended for users wanting to experiment and learn with a basic set of objects.
+  - **Blank**: Start with an empty project and no predefined objects.
+  - **IFC4 Demo Template**: Includes a basic set of common object types like bunny, windows, doors, and other basic elements with complex geometry.
 
-  This also shows other larger object libraries for steel and countries available with the BlenderBIM Add-on. These contain hundreds of objects and are not recommended to be loaded as a template.
+  The blank project is recommended for users who want to curate assets,
+  whereas the IFC4 Demo Template is recommended for users wanting to experiment
+  and learn with a basic set of objects.
+
+  The BlenderBIM Add-on provides other larger libraries containing hundreds of objects,
+  but loading them as a template is not recommended due to their size and complexity.
 
   .. seealso::
 
@@ -148,8 +154,8 @@ Fields
 |EXPORT| **Saved**
   Displays the last saved date and time of the loaded IFC file. Example: "2024-06-10 13:15"
 
-**File path**
-  Shows the location of the loaded IFC file on the user's file system. Example: "/home/user/Docum...lenderbim/demo.ifc"
+**IFC File**
+  Shows the location of the loaded IFC file on the user's file system. Example: "/home/user/Docum...lenderbim/demo.ifc". If part of the path is hidden by ellipsis, hovering over it will reveal the full file path.
 
 Buttons
 ^^^^^^^
@@ -161,7 +167,8 @@ Buttons
   This button allows users to choose and load a different IFC file. Clicking the button will open a file browser dialog, enabling users to navigate to and select the desired IFC file.
 
 **Unload the IFC project**
-  This button allows users to unload the currently loaded IFC file from the Blender scene. Clicking the button will remove the IFC data and clear the "Project Info" panel, switching it to the Project Setup Mode.
+  This button allows users to unload the currently loaded IFC file from the Blender scene.
+  Clicking the button will remove the IFC data and clear the "Project Info" panel, returning it to the `Project Setup Mode`_.
 
 
 Project Info Editing Mode
@@ -170,7 +177,15 @@ Project Info Editing Mode
 .. figure:: images/interface_property-editor_project-overview_edit-header.png
    :alt: Project Info when edit header toggle is active
 
-Clicking the pencil button (which doesn't exist when in the Project Setup Mode) switches the "Project Info" panel to `editing mode <Project Info Editing Mode_>`_, allowing users to modify the IFC header. The IFC Schema version can't be edited. You can upgrade the IFC schema when opening a file though.
+Clicking the pencil button (which doesn't exist when in the Project Setup Mode) switches the "Project Info" panel to `editing mode <Project Info Editing Mode_>`_, allowing users to modify the IFC header.
+
+The header section has information about:
+  - the IFC version used
+  - the application that exported the file
+  - the date and time when the export was done
+  - other optional user defined fields like the author's name, company and authorizing person of the file
+
+The IFC Schema version cannot be edited in this mode. However, you have the option to upgrade the IFC schema when opening a file.
 
 Fields
 ^^^^^^
@@ -195,7 +210,7 @@ Fields
   Displays the email address of the organization.
 
 **Authoriser**
-  Shows the authoriser of the IFC file, if available. Example: "Nobody"
+  Shows the authoriser of the IFC file. Example: "Nobody". The authoriser typically represents the person or entity responsible for approving the IFC file and its contents. 
 
 Buttons
 ^^^^^^^
@@ -213,7 +228,7 @@ Advanced Loading Mode
 ---------------------
 
 .. seealso::
-  :ref:`users/dealing_with_large_models:Filtered model loading`.
+  :ref:`users/advanced/dealing_with_large_models:Filtered model loading`.
 
 The Advanced Loading Mode is an additional mode that is available when loading an IFC file using the **Enable Advanced Mode** checkbox.
 
@@ -263,17 +278,64 @@ Fields
   When "Whitelist" or "Blacklist" is chosen, users can input a custom query in the "Filter Query" field to define the specific criteria for filtering elements.
 
 **Deflection Tolerance**
+  Maximum distance between a curved surface and its tessellation (mesh approximation).
+  Higher values result in a coarser tessellation, while lower values produce a finer mesh approximation.
+
+  .. seealso
+  
+    `IfcOpenShell deflection_tolerance <https://docs.ifcopenshell.org/ifcopenshell/geometry_settings.html#deflection-tolerance>`__
 
 **Angular Tolerance**
+  Maximum angle between adjacent face normals in a tessellation (mesh approximation).
+  Higher values result in a smoother tessellation, while lower values may produce more angular or faceted surfaces.
+
+  .. seealso
+  
+    `IfcOpenShell angular_tolerance <https://docs.ifcopenshell.org/ifcopenshell/geometry_settings.html#angular-tolerance>`__
+
 
 **Void Limit**
+  The maximum number of voids or openings an element can have before being considered excessive and skipped during the loading process.
+  Elements with a number of openings exceeding the specified limit will be excluded from the loaded model,
+  and a warning message will be displayed in the console, listing the skipped elements.
+
+  Openings slowdown the rendering process, so lower values result in improved performance.
 
 **Distance Limit**
 
-**False Origin**
+  Maximum distance between vertices in a tessellation (mesh approximation).
+  Higher values result in a coarser mesh, while lower values produce a denser mesh with more vertices.
+
+**False Origin Mode**
+  Sets the origin point or reference point for the loaded model geometry. This can be useful for aligning or positioning the model within the Blender scene.
+
+  There are three modes available for setting the False Origin:
+
+  - **Automatic**: An automatic false origin will be detected and applied based on the geometry with large coordinate values.
+    This mode is useful when the model's coordinates are extremely large or outside the typical Blender coordinate range.
+
+  - **Manual**: You can specify the false origin coordinates manually.
+    This mode allows you to enter the desired origin coordinates in the project's units (e.g., meters, millimeters) where the Blender origin (0,0,0) should be positioned.
+
+  - **Disabled**: The model will be loaded with its original local coordinates, without any false origin adjustments.
+    This mode is suitable when the model's coordinates are within the standard Blender coordinate range and do not require any origin shifting.
+
+  When the "Manual" mode is selected, an additional field **False Origin** will appear,
+  allowing you to enter the desired false origin coordinates in the project's units, separated by commas (e.g., "20.1,10.9,-3.1").
+
+  Applying a false origin can help prevent precision issues and ensure accurate positioning and scaling of the model within the Blender scene,
+  especially when working with large-scale projects or models with coordinates outside the typical Blender range.
 
 **Element Range**
-  Users can define a range of elements to load based on their index within the IFC file. This is useful for loading a specific subset of elements when dealing with large models.
+  Users can define a range of elements to load based on their index within the IFC file.
+  This is useful for loading a specific subset of elements when dealing with large models.
+
+  - **Element Offset**: Specifies the starting index of the elements to be loaded. 
+  - **Element Limit**: Specifies the maximum number of elements to be loaded from the specified offset.
+
+  For example, if the offset is set to 10 and the limit is set to 50, only 50 elements will be loaded, starting from the 11th element.
+
+  If no offset or limit is specified, all elements within the specified filter criteria will be loaded.
 
 
 Checkboxes