3 ms·

What's in them? Edit: Thinking more about it... The only thing I can think I would want in a low level design document would be something like extended comment

What's in them? Edit: Thinking more about it... The only thing I can think I would want in a low level design document would be something like extended comments on how a module or function works -- but if you need too much of this you probably have bad architecture or are using the wrong frameworks. We do use some of this kind of doc, both for ourselves and for the public, to help explain how our "Lego parts" fit together. Do you have any examples of the kind of doc you're talking about? Here's one we recently made: https://nebula.mimix.io/en/nebula/dev-guide https://nebula.mimix.io/en/nebula/dev-guide

ckrishnamoorthy 6y ago
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.

ckrishnamoorthy 6y ago

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.