diff --git a/api/mac_icon.cpp b/api/mac_icon.cpp
index fe8aaa834d..f8c26c658b 100644
--- a/api/mac_icon.cpp
+++ b/api/mac_icon.cpp
@@ -15,6 +15,19 @@
 // You should have received a copy of the GNU Lesser General Public License
 // along with BOINC.  If not, see <http://www.gnu.org/licenses/>.
 
+// THIS CODE IS OBSOLETE! A better way to add an icon to science applications
+// (or any Mac executable, including command-line tools) is:
+// [1] Select the application in the Finder
+// [2] Get Info (command-I) for the selected application
+// [3] Click on the file's current icon in the top left corner of the Get Info window
+// [4] Paste (command-v) the desired icon.
+//
+// To copy an icon from a different file:
+// [a] Get Info for the source file
+// [b] Click on the file's  icon in the top left corner of the Get Info window
+// [c] Copy (command-c) the icon.
+
+
 /* Mac-specific code to display custom icon for science application (optional)
    adapted from code written by Bernd Machenschalk.  Used with permission of the
    Einstein@home project.
diff --git a/api/make_app_icon_h.cpp b/api/make_app_icon_h.cpp
index 8c064a780b..cb91968556 100644
--- a/api/make_app_icon_h.cpp
+++ b/api/make_app_icon_h.cpp
@@ -19,6 +19,18 @@
 // Utility to convert *.icns file into app_icon.h file for use 
 // with api/setMacIcon() in science applications.
 
+// THIS CODE IS OBSOLETE! A better way to add an icon to science applications
+// (or any Mac executable, including command-line tools) is:
+// [1] Select the application in the Finder
+// [2] Get Info (command-I) for the selected application
+// [3] Click on the file's current icon in the top left corner of the Get Info window
+// [4] Paste (command-v) the desired icon.
+//
+// To copy an icon from a different file:
+// [a] Get Info for the source file
+// [b] Click on the file's  icon in the top left corner of the Get Info window
+// [c] Copy (command-c) the icon.
+
 #include "config.h"
 #include <cstdio>