How do you document unconventional code features?

One of the challenges I often face as a software developer is discerning unconventional code features amidst a sea of conventional ones. Once identified, it's vital to understand their scope, be it a function, module, or system-wide feature. Recognizing its relation to the overall project is key. Before documenting, a deep comprehension ensures I avoid discrepancies or omissions, ensuring others can swiftly grasp its intricacies.

Having a fair functional understanding of the product as a whole and the feature in particular along with how it fits in the requirement is the key to make decisions around documenting the workarounds. If there is knowledge of how the implemented workaround is different from the expected solution, then it can be documented in the right way as part of project documentation.

Architects usually tend to hold a particular angle on how something can/should be implemented. If you want to justify why you are taking a different route, a clear picture that highlights the bottlenecks in the expected solution versus benefits in the current solution will work wonders.

Any model or solution needs prototyping whether it be proof of concept or just presentations bazed on the need. Technical implementation details are best shared in an algorithmic way. The steps need to be precise and to the point.

Any implementation needs risk analysis before it begins. When you perform risk analysis, your team prepares for the dark days as well and the code that comes out is much closer to anticipated test scenarios.

Linking resources ensures a deep examination of the underlying implementation. It acts both as a source of attribution and an entry to extend the functionality. Consider it future-proofing when linking to documentation, since the underlying technology may change in the future and it would be helpful for backwards compatibility.

If unconventional code is the topic of this discussion, then to dovetail a formula for it would defeat the purpose -- By definition, it is not possible to strait-jacket unconventionality. Having said that, more than the code that needs to be documented; what is really needed is the fine understanding of whatever that caused the unconventional approach to be taken. Each member of the team needs to obtain "buy-in" first on the reasoning. I started writing TAD as a practicing architect (of the building variety) for use for designing my architectural projects. It's quite unconventional -- not just the code. A huge amount of time goes into the background theories on the "why" of TAD. Only then can people contribute to its the code.