339 karma · joined September 2, 2019
Ultimately any useful documentation needs active curation.
Getting devs to do this well is hard. Agents can be driven to do a fair job through suitable prompt frameworks and repetition eg as PR reviewers.
I’ve had reasonable success with a combination of space dimensions structured requirements and component based indexes and time dimensions of decision records and commits.
Also a strong design model to give common structure - hex arch with ports and adapters and pure business logic.
YMMV
These days I split between technical notes a write and store on the project git so others and the AI tools can read - eg architecture decision records, bug reports etc and then a separate personal linear time journal of what I’m doing / thinking/ task lists meeting notes etc, often with links to the project specific docs. Great for searching. What I miss from paper is ability to quickly sketch diagrams.
Had a tour of the place back in the day before 9/11 and all that made the world a lot less fun.
There’s a massive it depends, not all about basic performance.
ParcPlace acquired competitor Digitalk and tried to create a Frankenstein hybrid - jigsaw? - that royally screwed things up.
Around the time, the industry was very exercised about a number of features that alledgedly made PP Smalltalk bad:
- non-native widgets (emulated) for windows - who cares now;
- principal deployment as a single process, not natively multi-threaded, using internal virtual threads - which actually scales better;
- must be able to run in the browser like java applets - :-)
- can't get my head round "image" model, must have individual files
This was all FUD. Developing in VisualWorks with Envy (Gemstone) centralised version control was a blissful experience I haven't seen bettered.
But yes, Smalltalk and C++ faced off in industry for a number of years for the crown and then along came Java on the OSS tidal wave that effectively destroyed the business model for VisualWorks that relied on expensive licences.