diff --git a/doc/doxygen/src/porting-boards.md b/doc/doxygen/src/porting-boards.md
index 09613e1b79..7a0809b87c 100644
--- a/doc/doxygen/src/porting-boards.md
+++ b/doc/doxygen/src/porting-boards.md
@@ -125,21 +125,31 @@ FEATURES_PROVIDED += periph_uart
 ### Makefile.include                                         {#makefile-include}
 
 This file contains BSP or toolchain configurations for the `BOARD`. It
-should at least define the configuration needed for flashing (i.e. a
-programmer) as well as the serial configuration (if one is available).
+should at least define the configuration needed for flashing (i.e. specify a
+default programmer) as well as the serial configuration (if one is available).
+The default serial port configuration is provided by
+`makefiles/tools/serial.inc.mk` and define the following values for the serial
+port (depends on the host OS):
 
-e.g.:
+```
+PORT_LINUX ?= /dev/ttyACM0
+PORT_DARWIN ?= $(firstword $(sort $(wildcard /dev/tty.usbmodem*)))
+```
+
+So if the board is also using this, there's no need to redefine these variables
+in the board configuration.
+
+For example a board that is using a custom serial port (via an USB to serial
+adapter) and that is flashed using openocd by default would have the following
+content in its `Makefile.include`:
 
 ```mk
 # Define the default port depending on the host OS
 PORT_LINUX ?= /dev/ttyUSB0
 PORT_DARWIN ?= $(firstword $(sort $(wildcard /dev/tty.usbserial*)))
 
-# setup serial terminal
-include $(RIOTMAKE)/tools/serial.inc.mk
-
 # this board uses openocd
-include $(RIOTMAKE)/tools/openocd.inc.mk
+PROGRAMMER ?= openocd
 ```
 
 ## doc.txt                                                          {#board-doc}