News for hackers. Stuff that matters.
Re:Ask HN: Is there a better way to document complex softwar... by zzzzzzzza on Thursday November 22, 2018 @01:51AM (#18508336)
“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)

Re:Ask HN: Is there a better way to document complex softwar... by platz on Sunday November 25, 2018 @02:14PM (#18528352)
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
Re:Ask HN: Is there a better way to document complex softwar... by 6nf on Sunday November 25, 2018 @05:11PM (#18529392)
I don't need your flowcharts, I'll be heading for the door!
Re:Ask HN: Is there a better way to document complex softwar... by Aeolun on Sunday November 25, 2018 @07:39PM (#18530089)
Ah, it’s good they used varchar, at least now you can store everything in those columns.

And there’s a multitude of ways to soft-delete too!

This is much better than some schemas I’ve seen.

Re:Ask HN: Is there a better way to document complex softwar... by muthdra on Sunday November 25, 2018 @08:26PM (#18530315)
Not 2 years ago, I saw an entire Joomla schema converted to Microsoft Excel tables which we should use to port the website. Our team just ignored the effort.
Re:Ask HN: Is there a better way to document complex softwar... by thrower123 on Sunday November 25, 2018 @08:29PM (#18530326)
Probably the most important part of that effort was to keep the project managers and analysts busy fighting over that nonsense, providing aircover for the devs to actually do the work.
Re:Ask HN: Is there a better way to document complex softwar... by muthdra on Wednesday November 28, 2018 @02:47PM (#18554968)
Good guess but this is third world country public school level. The friendly sextagenarian did his best but he was only comfortable with PHP and Excel.
Re:Ask HN: Is there a better way to document complex softwar... by quickthrower2 on Sunday November 25, 2018 @02:44PM (#18528579)
Looks like a schema to allow the code to decide the real schema at runtime. A poor mans mongodb.
Re:Ask HN: Is there a better way to document complex softwar... by rco8786 on Sunday November 25, 2018 @04:24PM (#18529146)
This is pretty common looking for things like CRMs or CMSes where customer specific custom fields rule the day.
Re:Ask HN: Is there a better way to document complex softwar... by CMCDragonkai on Sunday November 25, 2018 @07:46PM (#18530113)
The database was meant to be the CMS and SQL was designed to be human readable.
Re:Ask HN: Is there a better way to document complex softwar... by josephg on Sunday November 25, 2018 @10:16PM (#18530780)
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.

Re:Ask HN: Is there a better way to document complex softwar... by enimodas on Monday November 26, 2018 @05:45AM (#18532406)
Sounds like the real problem is that there's too much friction with schema migrations.
Re:Ask HN: Is there a better way to document complex softwar... by platz on Sunday November 25, 2018 @03:04PM (#18528706)
This is only a slight exaggeration of real things that exist in products like SharePoint or Visual Studio Team Services
Re:Ask HN: Is there a better way to document complex softwar... by nafey on Sunday November 25, 2018 @02:36PM (#18528529)
That's scary to even read
Re:Ask HN: Is there a better way to document complex softwar... by zeroname on Sunday November 25, 2018 @09:03PM (#18530476)
> But my domain model is...

No it isn't. That's the model for the representation of the actual domain model. The actual domain model may well be "idk everything" (then you're SOL) or it just may not be formalized (then you might want to fix that).

Re:Ask HN: Is there a better way to document complex softwar... by mlthoughts2018 on Sunday November 25, 2018 @11:45AM (#18527547)
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.
Re:Ask HN: Is there a better way to document complex softwar... by zandl on Sunday November 25, 2018 @12:27PM (#18527769)
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.
Re:Ask HN: Is there a better way to document complex softwar... by amelius on Sunday November 25, 2018 @05:10PM (#18529384)
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.

Re:Ask HN: Is there a better way to document complex softwar... by toolslive on Sunday November 25, 2018 @02:15PM (#18528356)
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)