Updated with review comments fixes

Author: SenRamakri

docs/design-documents/README.md

@@ -1,12 +1,10 @@
-# Design Process for Mbed-OS
-This document defines the software design process for Mbed-OS. Anyone developing for Mbed-OS should use this process to submit the design to get it reviewed from the broader Mbed-OS developer community.
+# Design Process for Mbed OS
+This document defines the software design process for Mbed OS. Anyone developing for Mbed-OS should use this process to submit the design to get it reviewed from the broader Mbed-OS developer community.
 
 ## Design documents location and organization
-* It's suggested to write one design document per change, which could be a new feature, defect fixes, tools changes etc. Do not try to address multiple changes in the same document.
-* It's up to the judgement of developer to decide whether a change warrant a design document to go with it. For example, minor changes/small localized defect fixes may not need a design document.
 * The design document will follow the format represented in [Design Document Template](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md)
-
-* For each design submission, create a folder under *https://github.com/ARMmbed/mbed-os/docs/design-documents/{AREA OR COMPONENT}*. The area/component would be Drivers, Platform, Connectivity, Security, Peripherals etc. 
+* For each design submission, create a folder under *https://github.com/ARMmbed/mbed-os/docs/design-documents/* at the appropriate level. The directory structure under design-documents is organized to align with mbed-os directory structure.
+  It is ok to create new sub-directories to organize similar items together. 
   If your implementation is creating new APIs, you should try to match the folder name directly to the new API, otherwise 
   use the title of the feature as the folder name. 
   For example, if your implementation is adding new EMAC API, you may name the folder as **New_EMAC_API** or if you are creating a new Serial Driver for Mbed-OS you may name the folder as **Serial_driver_for_Mbed-os**.
@@ -19,26 +17,23 @@ This document defines the software design process for Mbed-OS. Anyone developing
 Its highly encouraged to create diagrams to depict your software design. The [Design Document Template]((https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md) provided here uses diagrams generated using draw.io. draw.io generates XMLs for each diagram and those corresponding XMLs are also provided under the diagrams folder, and you are free to use that as your reference for generating your own diagrams. And, when you are generating your own diagrams it would be better to provide the metadata/other files(e.g, if you are using draw.io provide XMLs from draw.io) required for future editing of those diagrams.
 
 ## Design Process
-* Developer generates a design document located under *https://github.com/ARMmbed/mbed-os/docs/design-documents/{AREA OR COMPONENT}* and generates a pull-request to Mbed-OS.
-  * NOTE: If you are part of an organization and would like to do design review within your organization before landing the pull-request, its ok to do so.
-  * The pull request may also include the initial code implementation. It's upto to the develper to decide if the initial implementation comes along with the design document or later.
-  * Although, if you are planning a large change, its encoraged to start the design review early before the implementation. This also help to avoid major re-work of your implementation if required by the design review.
+* Developer generates a design document located under *https://github.com/ARMmbed/mbed-os/docs/design-documents/* and generates a pull-request to Mbed-OS.
+  * It's upto to the develper to decide if the initial implementation comes along with the design document or as separate PRs. 
+  * Although, if you are planning a large change, its encouraged to start the design review early before the implementation. This also helps to avoid major re-work of your implementation if required by the design review.
+  * The initial submission of the design document doesn't need to be complete or refined in terms of capturing all the details, as you may use the design document itself to brainstorm and discuss on your idea or new feature being proposed.
 * Design review follows the same process as code review. Please refer contribution process as outlined in [Contributing to Mbed-OS](https://os.mbed.com/contributing/) for more information.
 * Once the design is approved, implementation is completed/adjusted according to the latest design document. Developer can create the pull-request with the final implementation, if its coming separately.
 
 ## Capturing future changes to design
-If your implementation changes in future, corresponsding design documents may be updated to capture the new design.
+If your implementation changes in future, corresponding design documents should be updated to capture the new design.
 It's possible that a new implementation may require changes to some previous implementations. In that case, capture
-the new changes in the original design document as well. Also create references to other(or older) design documents in the
-References section for the new design document.
+the new changes in the original design document as well. 
 
 ## General guidelines for creating design documents
-Its up to the developer to make a judgement on whether a design docucment is required for a change. It may not be required for minor fixes and small localized changes. But for changes with lot of code turmoil across multiple components or if its new feature or functionality being added its best to have a backing design document. Its also ok for developers to gather initial feedback on some idea before they decide to implement. Its also not absolutely necessary that implementation should be started only after design document review. The caveat here is if the proposed design is changed significantly in the process of review it will impact your implementation as well. Thus for large features where lot of design feedbacks are expected it's advisable to start your implementation once major feedbacks are captured. For example, API designs can invite lot of feedbacks. In such cases, its best to capture those feedbacks before starting the implementation cycle. But for very localized implementations not impacting other parts of the system/APIs it may be ok to provide an initial implementation(in the same PR) as a reference along with design document.
+It's up to the developer to make a judgement on whether a design document is required for a change. It may not be required for minor fixes and small localized changes. But for changes with lot of code turmoil across multiple components or if it's new feature or functionality being added it's best to have a backing design document. Its also not absolutely necessary that implementation should be started only after design document review. The caveat here is if the proposed design is changed significantly in the process of review it will impact your implementation as well. Thus for large features where lot of design feedback are expected it's advisable to start your implementation once major feedback are captured. For example, API designs can invite lot of feedback. In such cases, it's best to capture those feedback before starting the implementation cycle. But for very localized implementations not impacting other parts of the system/APIs it may be ok to provide an initial implementation(in the same PR)as a reference along with design document.
 
 ## Reference documents
 [Design Document Template](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/design_template.md)
-
 [Example Design Document](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/example_feature_design/example_feature_design.md)
-
 [Design process](https://github.com/ARMmbed/mbed-os/blob/master/docs/design-documents/README.md)
 

docs/design-documents/design_template.md

@@ -20,7 +20,7 @@ Write your feature title above, in this case its "Mbed-OS Design Document"
     - [Custom Headings Here](#custom-headings-here)
 
 ### Revision history
-1.0 - A brief description for this version, e.g. Initial revision - Author name - Date
+1.0 - A brief description for this version, e.g. Initial revision - Author name - Date. NOTE: You may also specify the Mbed OS version this revision of design-document applies to.
 1.1 - Added new section - Author name - Date
 
 # Introduction
@@ -45,8 +45,8 @@ for a communication peripheral/device then the high level design goals could be
 * `Reading from and Writing to the device` - Read and Write interfaces should be implemented to support sending single/multiple bytes. 
 * `Resetting the device` - Functionality to reset the device should be provided.
 
-**NOTE: If you already have supporting architecture documentation in the form of technology documents or other existing documents
-feel free to link them here and use that, you don't have to replicate the same documentation here.**
+**NOTE: If you already have publicly available supporting architecture documentation in the form of technology documents or other existing documents
+feel free to link them here and use that, you don't have to replicate the same documentation here. **
 
 For each high level design goal, provide detailed software design under [Detailed Design](#detailed-design) section providing more details on implementation.
 

docs/design-documents/drivers/README.md

@@ -0,0 +1 @@
+# Design Documents - Drivers

docs/design-documents/features/connectivity/README.md

@@ -0,0 +1 @@
+# Design Documents - Connectivity

docs/design-documents/features/filesystem/README.md

@@ -0,0 +1 @@
+# Design Documents - Filesystem

docs/design-documents/features/security/README.md

@@ -0,0 +1 @@
+# Design Documents - Security

docs/design-documents/features/storage/README.md

@@ -0,0 +1 @@
+# Design Documents - Storage

docs/design-documents/hal/README.md

@@ -0,0 +1 @@
+# Design Documents - Hardware Abstraction Layer

docs/design-documents/platform/README.md

@@ -0,0 +1 @@
+# Design Documents - Platform

docs/design-documents/rtos/README.md

@@ -0,0 +1 @@
+# Design Documents - RTOS

docs/design-documents/tools/README.md

@@ -0,0 +1 @@
+# Design Documents - Tools