5 ms·

“Show me your flowcharts (source code), and conceal your tables (domain model), and I shall continue to be mystified; show me your tables (domain model) and I w

“Show me your flowcharts (source code), and conceal your tables (domain model), and I shall continue to be mystified; show me your tables (domain model) and I won’t usually need your flowcharts (source code): they’ll be obvious.” ~ Fred Brooks, “The Mythical Man Month” Stuff that has improved or the potential to improve the documentability of modern systems, imo: postgREST, custom types (e.g. domains in postgresql), more expressive type systems e.g. rust, haskell, typescript perhaps (though I am not completely sold on typescript yet myself) nix/nixos (or more mainstream, hashicorp products/ansible/puppet/docker) kubernetes and co. (most people probably don't need)

mlthoughts2018 8y ago
Absolutely this! No matter what the system is, the important part is being able to laser down to any lower levels of abstraction and reason about the specifics there. Higher level abstraction docs are summaries or getting started guides at best.
- zandl 8y ago
  Agreed as well, though there is also the case of communicating the high level flows to others that are not software experts so that everyone has a common understanding and doesn’t have to rely on a few key developers with the knowledge. Most smart folk who aren’t developers reason pretty well about architectures so you want them to be self sufficient too.
platz 8y ago
But my domain model is Store ===== Id int Col1 varchar Col2 varchar Col3 varchar ... Col134 varchar foreignKey1 varchar foreignKey1Type varchar foreignKey2 varchar foreignKey2Type varchar ... foreignKey10 varchar foreignKey10Type varchar validFrom varchar validTo varchar isActive boolean deleted boolean
- nafey 8y ago
  That's scary to even read
- quickthrower2 8y ago
  Looks like a schema to allow the code to decide the real schema at runtime. A poor mans mongodb.
  - platz 8y ago
    This is only a slight exaggeration of real things that exist in products like SharePoint or Visual Studio Team Services
  - rco8786 8y ago
    This is pretty common looking for things like CRMs or CMSes where customer specific custom fields rule the day.
    - CMCDragonkai 8y ago
      The database was meant to be the CMS and SQL was designed to be human readable.
      - josephg 8y ago
        Counterpoint: If small design decisions require global SQL schema changes, it slows you down. And small barriers to change will, in aggregate, kill you. Eg, over a month of iterations: "Can we add another field to user registration? It should be free text. Oh, they should select from a list. No wait, make it a date. Actually a date and a text field. No wait, dump the text field." Sometimes slowing down these changes is a good thing. But often, being able to ship each iteration along the way will help your design team converge on the best solution. If you need to write a schema migration for every iteration, it kills the ability of your team to experiment and explore the space of "what should our product actually look like". Faster iterations = more iterations = better product in the long term. Sometimes the best long term result requires some random stuff getting crammed into a big JSON field in your database in the short term.
toolslive 8y ago
There are exceptions though, where the domain model is trivial, but you will be mystified without the sequence diagrams. Paxos for example has a trivial domain model (a value that's supposed to be kept identical on all nodes in a distributed system) but the consensus algorithm is non-trivial enough that a lot of people claim you should not even try to implement it (and opt for Raft)
amelius 8y ago
Also as a user! User documentation should imho explain what are the datastructures that a piece of software is manipulating, and what the dependencies between them are. The rest of the UI, I can figure out by myself.

mlthoughts2018 8y ago

Absolutely this! No matter what the system is, the important part is being able to laser down to any lower levels of abstraction and reason about the specifics there. Higher level abstraction docs are summaries or getting started guides at best.

zandl 8y ago
Agreed as well, though there is also the case of communicating the high level flows to others that are not software experts so that everyone has a common understanding and doesn’t have to rely on a few key developers with the knowledge. Most smart folk who aren’t developers reason pretty well about architectures so you want them to be self sufficient too.

platz 8y ago

But my domain model is Store ===== Id int Col1 varchar Col2 varchar Col3 varchar ... Col134 varchar foreignKey1 varchar foreignKey1Type varchar foreignKey2 varchar foreignKey2Type varchar ... foreignKey10 varchar foreignKey10Type varchar validFrom varchar validTo varchar isActive boolean deleted boolean

nafey 8y ago
That's scary to even read
quickthrower2 8y ago
Looks like a schema to allow the code to decide the real schema at runtime. A poor mans mongodb.
- platz 8y ago
  This is only a slight exaggeration of real things that exist in products like SharePoint or Visual Studio Team Services
- rco8786 8y ago
  This is pretty common looking for things like CRMs or CMSes where customer specific custom fields rule the day.
  - CMCDragonkai 8y ago
    The database was meant to be the CMS and SQL was designed to be human readable.
    - josephg 8y ago
      Counterpoint: If small design decisions require global SQL schema changes, it slows you down. And small barriers to change will, in aggregate, kill you. Eg, over a month of iterations: "Can we add another field to user registration? It should be free text. Oh, they should select from a list. No wait, make it a date. Actually a date and a text field. No wait, dump the text field." Sometimes slowing down these changes is a good thing. But often, being able to ship each iteration along the way will help your design team converge on the best solution. If you need to write a schema migration for every iteration, it kills the ability of your team to experiment and explore the space of "what should our product actually look like". Faster iterations = more iterations = better product in the long term. Sometimes the best long term result requires some random stuff getting crammed into a big JSON field in your database in the short term.

toolslive 8y ago

There are exceptions though, where the domain model is trivial, but you will be mystified without the sequence diagrams. Paxos for example has a trivial domain model (a value that's supposed to be kept identical on all nodes in a distributed system) but the consensus algorithm is non-trivial enough that a lot of people claim you should not even try to implement it (and opt for Raft)

amelius 8y ago

Also as a user! User documentation should imho explain what are the datastructures that a piece of software is manipulating, and what the dependencies between them are. The rest of the UI, I can figure out by myself.