Correct the docs (no substantial changes, mostly grammar and formatting) (#1)

* Correct the docs (no substantial changes, mostly grammar and formatting)

* Add links to Babel and DCP

* Fixes for release preparation v0.1 (#3)

* source files consistency fix

* Delete part B.brd

* Revert "Delete part B.brd"

This reverts commit 4a45031.

* Revert "source files consistency fix"

This reverts commit 015ba01.

* fixes for #1

* Update readme.md

* Update readme.md

* Update manufacturing/readme.md

Co-authored-by: Pavel Kirienko <pavel.kirienko@gmail.com>

* Update readme.md

* Update readme.md

* Update readme.md

Co-authored-by: Alexander Sysoev <alexander.sysoev@zubax.com>
Co-authored-by: Pavel Kirienko <pavel.kirienko@gmail.com>

Co-authored-by: j3qq4hch <j3qq4hch@gmail.com>
Co-authored-by: Alexander Sysoev <alexander.sysoev@zubax.com>

Author: 3 people

README.md

@@ -1,38 +1,56 @@
 # Babel-Babel
+
 All-in-one hardware solution for developing UAVCAN-compatible devices.
 
-Babel-Babel consists of three devices that are assembled on a single PCB: 2 Babel USB-CAN adapters and dronecode probe (a generic JTAG/SWD + UART console adapter).
+Babel-Babel consists of three devices that are assembled on a single PCB:
+2x [Babel](https://zubax.com/babel) USB-CAN adapters and a
+[Dronecode probe](https://shop.zubax.com/collections/development-tools/products/dronecode-probe-v2-2-jtag-swd-adapter-usb-uart-adapter-with-dcd-m-cable)
+(a generic JTAG/SWD + UART console adapter).
+
+Babel-Babel is connected to the PC with a single USB cable as it contains a built-in USB hub.
+It provides the following interfaces for connecting to the device under development:
 
-Babel-Babel is connected to a PC with only one USB cable as it contains a USB HUB. It provides the following interfaces for connecting to a device under development:
 - CAN 1 (UAVCAN micro connector)
 - CAN 2 (UAVCAN micro connector)
-- SWD and UART (DroneCode Debug connector, medium)
+- SWD and UART (Dronecode Debug connector, medium)
 - USB (regular USB A connector)
 
-Along with that, all these interfaces are connected to additional PLS connectors (regular 0.1` single row pin headers). 
+Along with that, all these interfaces are routed to additional PLS connectors (regular 0.1' single-row pin headers).
 These connectors may be used for production testing purposes.
 
-Each individual Babel can be turned off using the corresponding dip switch.
+Each Babel can be turned off using the corresponding dip switch.
+
+For technical characteristics, please refer to `requirements.md`.
+
+## Standalone debug tool
 
-## Standalone debugging tool 
-In standalone debugging tool using scenario (when pin headers are not used) Babel-Babel is constructed using a "novel approach" often called oreo-construction.
-This eliminates the need for having a separate housing, reliably protecting all the electronics inside the device
-while also providing a possibility to deposit some explanatory notes on the top surface of the device 
-(like connectors purpose, pinouts, etc.) without additional technological process, which allows Babel-Babel to be a relatively self-documented device.
+When the device is used as a standalone debug tool (when the pin headers are not used),
+Babel-Babel is constructed using a "novel approach" often called oreo-construction.
+This approach eliminates the need for having separate housing,
+reliably protecting all the electronics inside the device
+while also providing a possibility to deposit some explanatory notes on the top surface of the device
+(like the purpose of connectors, pinouts, etc.) without any additional technological processes,
+which allows Babel-Babel to be a relatively self-documenting device.
 
 ![](figures/General_view.png)
 
 ![](figures/Pinout.png)
 
 ## Production flashing tool
-In order to use Babel-Babel as production flashing and testing tool, an adapter PCB should be designed.
-In general, this PCB should have PBS connectors for Babel-Babel on one side and some sort of connectors for the device under test (usually pogo pins).
-Both Babel-Babel and device under test can then be connected to this adapter PCB and the flashing and testing routine can be performed.
-Although using Babel-Babel for testing requires some preparations, 
-it still may be beneficial as it greatly reduces the total amount of wiring and connectors involved in the production testing routine.
-This in turn makes the process faster, more reliable and less painstaking. 
-A good example of this practice is Myduck-LV.
-It is a device used to flash and test Mitochondrik LV.
-In order to avoid the requirement for an additional adapter PCB Myduck LV is designed to accept Babel-Babel directly: 
+
+To use Babel-Babel as a production flashing and testing tool, an adapter PCB should be designed.
+In general, such PCB should have PBS connectors for Babel-Babel on one side and some connectors
+for the device under test (usually pogo pins).
+Both Babel-Babel and the device under test can then be connected to this adapter PCB and
+the flashing and testing routine can be performed.
+
+Although using Babel-Babel for testing requires some preparations,
+it still may be beneficial as it greatly reduces the total amount of
+wiring and connectors involved in the production testing routine.
+This, in turn, makes the process faster, more reliable, and less painstaking.
+
+MyDuck-LV is a good example.
+It is a device used for flashing and testing [Mitochondrik-LV](https://zubax.com/mitochondrik-lv).
+To eliminate additional adapter PCBs, MyDuck-LV is designed to host Babel-Babel directly:
 
 ![](https://github.com/Zubax/MyDuck-LV/blob/master/figures/Myduck-LV-jig.png)

manufacturing/readme.md

@@ -1,16 +1,24 @@
 # Babel-Babel manufacturing
 
-Following operations must be performed for Babel-Babel manufacturing:
+The following operations must be performed for Babel-Babel manufacturing:
 
 1) SMT mounting of the main PCB.
 
-2) Flashing both Babels and Dronecode probe on the PCB.
-This operation should be performed without installing any connectors on the PCB.
-4 pin pogo pin connector should be used.
+2) Flashing both Babels and [Dronecode probe](https://github.com/Zubax/dronecode_probe) on the PCB.
+This operation should be performed without installing any connectors on the PCB,
+a 4-pin pogo pin connector should be used instead.
 Connectors' pinouts used for flashing can be found in the picture below.
+
 ![](../figures/flashing_interface.svg)
 
-3) After flashing is done, all the necessary PCBs should be stacked and aligned and secured together using 5 2 mm diameter shafts.
-Part A PCBs should be preliminary split in two parts, excessive material that interferes with USB A connector should be removed. 
+3) After flashing is done, all the PCBs should be stacked, aligned,
+and secured together using x5 2 mm diameter pins.
+"Part A" PCBs should be split in two parts beforehand,
+and the excessive material that interferes with USB A connector placement should be removed.
+The pins can be manufactured by cutting widely available round wooden dowels 
+with 2 mm diameter to appropriate length (7.7 mm).
+The dowels can be purchased in general hardware stores 
+or on [Amazon](https://www.amazon.co.uk/Wooden-Sticks-Round-Dowels-Natural/dp/B07T4ZFFHQ)
+and other online shops.
 
 ![](../figures/blow_scheme.svg)

requirements.md

@@ -1,32 +1,30 @@
-# Babel-Babel combined debugger and interface converter business requirements
+# Business requirements for Babel-Babel
 
 ## Purpose
 
-Babel-Babel is a device intended to ease the process of manufacturing flashing and testing of Zubax products (or any other similar products).
-Besides that, the device can be used as a tool for UAVCAN-compatible embedded devices.
-One Babel-Bable can replace two USB-CAN converters, a programmer and also can provide one USB 2.0 port for connecting of the device being debugged.
-All this requires only 1 USB connection to the host PC.
+Babel-Babel is a device intended to ease the process of flashing and testing of Zubax products (or similar products).
+Besides that, the device can be used as a tool for developing and debugging UAVCAN-compatible embedded devices.
+One Babel-Babel can replace two USB-CAN converters, a programmer, and provide one free USB 2.0 host port.
+All this requires a single USB connection to the host PC.
 
 ## Technical requirements
 
-
-* small size.
-* minimizing the required USB connections number for the host PCB to the debugging tools.
-* minimizing the required cable connections number to the device under test.
-* The hardware should be compatible with the existing software for Babel and DCP 2.3. 
+* Small size.
+* Minimizing the number of required USB connections to the host PCB.
+* Minimizing the number of required cable connections to the device under test.
+* The hardware should be compatible with the existing software for Babel and DCP 2.x.
 
 ## Design requirements
 
-* USB connectors should be able to tolerate moderate mechanical abuse. 
-* Enclosure class IP40
+* USB connectors should be able to tolerate moderate mechanical abuse.
+* Enclosure class IP40.
 * Standard Dronecode connector should be used for SWD interface and debug UART.
-* USB-CAN converters should be compatible with UAVCAN hardware recommendations.
+* USB-CAN converters should be compatible with Dronecode DS-015 hardware design recommendations.
 * The device should be powered from the USB bus (4.5 - 5.5 V, current consumption up to 500 mA).
+* Usage of non-AEC-Q grade components, as well as deviations from the hardware development policies, are allowed.
 
-## Environmental conditions.
+## Environmental conditions
 
 * In-door usage.
 * Operating temperature range - 0..+40C
-* Operating Humidty - up to 100% 
-
-Using non-AEC-Q grade components as well as deviations from the hardware development policies is allowed.
+* Operating humidty - up to 100%