Markdown becomes source code, moving to /src directory

The proposal to include Markdown in the /src directory represents a significant shift in how documentation is viewed within software development. Traditionally, documentation has been kept separate from the actual code, often leading to discrepancies and difficulties in maintaining alignment between the code and its specifications. By storing Markdown alongside the source code, developers can ensure that the two remain in sync, thereby improving clarity and reducing the risk of miscommunication.

Adopting this practice may require teams to rethink their existing workflows, particularly in how they integrate documentation into their development processes. This could involve training developers on new practices for creating and maintaining Markdown files, as well as establishing guidelines for when and how to document code changes. However, the benefits of having all relevant information in one location could outweigh the initial learning curve, leading to a more efficient development cycle.

This approach does have limitations, particularly in terms of the types of documentation that remain outside of the /src directory. Higher-level design documents, project management tools, and issue trackers still play a vital role in the broader context of software development. Therefore, while Markdown as source code can enhance immediate understanding and locality, it may not completely replace other forms of documentation that serve different purposes in project management.