diff --git a/docs/guides/quickfort-user-guide.rst b/docs/guides/quickfort-user-guide.rst
index 9dda52454..c12df3eee 100644
--- a/docs/guides/quickfort-user-guide.rst
+++ b/docs/guides/quickfort-user-guide.rst
@@ -1992,10 +1992,10 @@ All stockpiles support the following properties:
 Property          Description
 ================  ===========
 ``name``          the name of the stockpile
-``take_from``     comma-separated list of names of stockpiles or workshops that
-                  the stockpile takes from
-``give_to``       comma-separated list of names of stockpiles or workshops that
-                  the stockpile gives to
+``take_from``     comma-separated list of names or building ids of stockpiles
+                  or workshops that the stockpile takes from
+``give_to``       comma-separated list of names or building ids of stockpiles
+                  or workshops that the stockpile gives to
 ``links_only``    if set to ``true`` then the stockpile will only take from
                   links
 ``barrels``       the number of desired barrels
@@ -2014,6 +2014,12 @@ Property          Description
                   feature
 ================  ===========
 
+Note that specifying building IDs in ``take_from`` or ``give_to`` lists is
+primarily useful when dynamically generating `quickfort` blueprints and
+applying them via the API. You will not generally know the ID of a stockpile or
+building when writing a blueprint by hand or when preparing a blueprint to
+apply in a different fort.
+
 #build mode reference
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -2023,8 +2029,8 @@ accept the ``name`` property.
 Moreover, all workshops and furnaces accept the ``max_general_orders``
 property, which sets the maximum number of general workorders that the building
 can accept, and the ``take_from`` and ``give_to`` properties, which are
-comma-separated lists of names (the same as the correponding stockpile
-properties above).
+comma-separated lists of names or building ids (the same as the correponding
+stockpile properties above).
 
 ================= ============================= ==========
 Symbol            Type                          Properties
@@ -2141,7 +2147,8 @@ Symbol            Type                          Properties
                                                 route stop on this track stop
                                                 and make it take from the given
                                                 comma-separated list of
-                                                stockpile names. ``route``: add
+                                                stockpile names or stockpile
+                                                building ids. ``route``: add
                                                 this route stop to the named
                                                 route. if no route of this name
                                                 exists, it will be created. If