Christian Casini
Macros are crucial to building on Polkadot. However, there isn't a dedicated documentation section that describes how macros are used in substrate and frame. Based on developer feedback, macro error handling is one of the main issues developers struggle with the most. This is because there is little documentation about macros ( and if there is, it's tough to find or not that straightforward).
There should be a dedicated documentation section that states:
  1. A comprehensive list of all the macros used in substrate and frame ( we could also add ink!).
  2. Examples of how different macros are used correctly ( coding examples)
  3. Tutorials on how to properly use macros in your code.
This would be a lot of work. But it would provide much value for existing Polkadot developers and new developers who want to enter the ecosystem.
Update to the post written above:
I did find this https://docs.substrate.io/reference/frame-macros/ but it states that the documentation is outdated. Updating this information would provide a good starting point. It can be further improved by:
  1. Step-by-Step Tutorials: Create step-by-step tutorials that guide developers using each macro in a practical scenario. Include explanations of why and when each macro is used.
  2. Visual Aids: Use diagrams or flowcharts to illustrate how macros work and interact with other system components.
  3. Sample Projects: Provide sample projects or templates that showcase the implementation of macros in a complete runtime setup. Developers can use these projects as a reference or starting point.