3 ms·

Thanks for taking the time to reply. Your dev guide looks very good. Yes, i am referring to detailed comments, interface details , return values etc. I am ref

Thanks for taking the time to reply. Your dev guide looks very good. Yes, i am referring to detailed comments, interface details , return values etc. I am referring to even more details in low level design. Like Class diagrams, sequence diagrams, and even list of SDK functions. I am all for documenting external facing REST api or SDK interfaces, since that would be anyway part of product documentation ( as the REST api or SDK is the product itself ). I agree, some of this is subjective, but at what level of detail do we stop, detailing out. I see value in a high level design and architecture diagram.

mimixco 6y ago
Thank you for your kind reply. I totally agree better doc is needed to tie the actual code to its intended functions and architecture. One problem I've had repeatedly with writing this kind of doc is that it immediately goes out of date as soon as you refactor -- which we do often! That kind of low-level doc isn't something you need every day, but when you are chasing an ugly bug, it can be awfully helpful to have some plain English explanation how two functions relate to each other, or how their arguments are used -- since this is the source of most bugs. Right now, it's very difficult to get doc that fully aligns your architecture diagrams with the actual code, function names, parms, etc. To us, this is the Holy Grail and part of what we are trying to built at Mimix. Using our MSL language, we plan to bring some of these kind of reuse and code diagramming features to the wiki editing environment.