diff --git a/firmware/Makefile b/firmware/Makefile
index 926ce59abf..7e626dd61d 100644
--- a/firmware/Makefile
+++ b/firmware/Makefile
@@ -1,6 +1,6 @@
 ##############################################################################
-# Build global options
-# NOTE: Can be overridden externally.
+# see readme.md
+# see setup_linux_environment.sh but Windows is also totally fine
 #
 
 CHIBIOS = ChibiOS
diff --git a/firmware/build-notes.txt b/firmware/build-notes.txt
index 2936ceddf1..c118a85840 100644
--- a/firmware/build-notes.txt
+++ b/firmware/build-notes.txt
@@ -1,46 +1 @@
-
-This directory contains the source code for the RusEFI firmware.
-
-The ideal is that typical end users should be able to use pre-built
-firmware.  They should not need to modify or even rebuild from the
-source code for basic use, but building from the source code provides
-the opportunity for optimization, supporting unexpected engine
-configurations, and specialized enhancements.
-
-
-TL;DR
-
-make PROJECT_BOARD=microrusefi PROJECT_CPU=ARCH_STM32F4
-
-
-Environment
-
-Rebuilding from source code requires this firmware, a modern C/C++
-compiler for embedded ARM systems, and a platform that supports 'make'
-based builds.
-
-While many compilers have the potential to work, we suggest using the
-official ARM version of GCC available at launchpad.net.
-
-Linux and MacOS systems should have the software development tools,
-primarily 'make', pre-installed or readily installed.  MS-Windows
-requires selecting and installing a Unix-compatible system environment.
-
-Note that the developers are volunteers, with varied motivations.
-These motivations often include using leading-edge language and build
-system concepts, requiring recent versions of tools.  Should you
-encounter build problems, review the latest version of this document.
-
-
-Expected Future Changes
-
-The firmware build is moving toward a system that separates board
-features from processor features.  This will require specifying both
-the board type and specific processor.
-
-The existing system evolved based on the original RusEFI boards which
-used 'STM32 Discovery' development boards plugged into base boards
-that held the ECU specific chips.  That resulted in hard-coded
-assumption about pin assignments, and associations of hardware with a
-specific processor variant.  That legacy is slowly being cleaned up,
-but is still evident in some settings and limitations.
+See readme.md
\ No newline at end of file
diff --git a/firmware/readme.md b/firmware/readme.md
index 4cf0f89449..36b4cd1d22 100644
--- a/firmware/readme.md
+++ b/firmware/readme.md
@@ -16,15 +16,16 @@ configurations, and specialized enhancements.
 
 TL;DR
 
-make PROJECT_BOARD=microrusefi PROJECT_CPU=ARCH_STM32F4
+``make PROJECT_BOARD=microrusefi PROJECT_CPU=ARCH_STM32F4``
 
-
-Environment
+# Environment
 
 Rebuilding from source code requires this firmware, a modern C/C++
 compiler for embedded ARM systems, and a platform that supports 'make'
 based builds.
 
+See setup_linux_environment.sh
+
 While many compilers have the potential to work, we suggest using the
 official ARM version of GCC available at launchpad.net.
 
@@ -37,16 +38,3 @@ These motivations often include using leading-edge language and build
 system concepts, requiring recent versions of tools.  Should you
 encounter build problems, review the latest version of this document.
 
-
-Expected Future Changes
-
-The firmware build is moving toward a system that separates board
-features from processor features.  This will require specifying both
-the board type and specific processor.
-
-The existing system evolved based on the original RusEFI boards.  Those
-used 'STM32 Discovery' development boards plugged into base boards
-that held the ECU-specific chips.  That approach resulted in hard-coded
-assumption about pin assignments, and associations of hardware with a
-specific processor variant.  That legacy is slowly being cleaned up,
-but is still evident in some settings and limitations.