Doesn't that assertion confuse statistics (data we have) with probability (data we should have got if it followed the rules) ? Calculus follows the latter idea of `simple rules will predict complex data`.:rose:

What will be the actionable intelligence (ai) that you are trying to offer, and do you expect folks to gather that (ai) from what you say, or what they will read, when they get a copy of the slide deck? If you know those things, clearly, and concisely, then you have a chance. However you also need to know what the readers, listeners, and attenders of the presentation want to hear - what is their particular 'doubt' that you need to address. Now you have a proper handle on the importance and priority of just how good your story needs to be. In some cases it's just a place holder so you can pick it up later, other times it's a 'now or never' commitment. Plenty of preparation prevents p*ss poor performance!

Gerry Schmitz wrote:

My documentation mostly consists of (control) tooltips.

Ooh, I really hate apps that assume that I will have the same mental model as the developer, especially when I don't ;). The expectations can easily lead into traps one can't get out of, and worse, ditching the app or tool. That said, it is really frustrating trying to explain something when you haven't established common ground from the start (the "your breakfast may be different from mine" problem). So at least having a purpose, concepts and usage approach documented will give users a clue as to where the code is going, especially if the app is 'special' (i.e. different to regular expectation).

It is worth having a look at the way the Git project writes it's Commit messages and it's documentation in terms of shifting from a subjective style of writing about what happened, to an objective imperative style. After a while of following along you start to see how you can stop apologising for what happened, and instead assert what is happening. We are taught (English 101) to write long waffle sentences, rather than short, concise and informative ones that we really need here. git/Documentation/SubmittingPatches at master · git/git · GitHub[^] The "Describe your changes well" section is a good start.

It's a 'source of truth' problem. A well labelled complete flow diagram pre-defines the structure. Meanwhile a rambling weasel word requirements document is, well, rarely complete, even conceptually. So, for A very comprehensive and precise spec | CommitStrip[^] ...

It's not "spaghetti code", it's "Flow Diagram code". An easy 1:1 direct conversion. As long as the customer continues to use a Flow (aka State) Diagram as the documentation, then it's Knex spaghetti for the win! Naming the `goto` junction points is hard, but then naming is hard anyway. Customer is likely to adopt your naming anyway if they haven't already named things (states) :rolleyes: .

There is no perfectly 'right' answer, and it depends on the state and type of the two car batteries, and the quality/capability of the alternator on the 'better' vehicle. Historically, the main issue was that the alternator diodes would 'blow' during the jump-start if the donor car was running. The surge current into the dead car's starter was too high, especially with good jump-lead connections. You also need the donor car and it's battery to have enough capacity when the two vehicles are initially connected (both vehicles off, mediocre donor trying to feed large dead battery could result in two nearly dead batteries, sigh). Then there a lot of 'safety' choices as to which leads to connect securely first, and what happens when a lead slips, hence it's normal to connect the two chassis last (little chance of failure and short circuit at this stage, compared to slipping of the power terminal). That said, on larger modern vehicles the alternator diodes now have good capacity (see articles/ videos [e.g. merlin's garage] on using them as welders!) so blowing the diodes on those beasts is less likely. Finally, just because there's a lovely big terminal next to the battery's negative, doesn't mean it is actually a secondary chassis connection. On my car it's the common point for the positive connections - Oops.

Just what is this consciousness that makes you Human? Does this question assert an untruth? :rolleyes:

There's a subtle difference between production ready, and functionally complete. It's (for me) always worth thinking through what the functionally complete (System Engineered) version could include and how it may become over complex with contradictory requirements. Sometimes there are subtle choices that lead to the death-march pit of doom while a slightly different choice would clearly signpost the sunlit uplands of future success. Then you can focus on the core element, the 'spike', where the tyres hit the road and the concepts hits the existing code, and neater approaches to the same functionality do start to emerge. Moving fast, always broken, like a bull in a china shop, is not a good look! Production ready is good, full function extendable is even better ;-)

It's like driving a car with 4 extra seats and a top speed of >85mph to the shops across the street. And then, when you take it in for a simple repair, no-one has the replacement part in stock. Name's Logic, Applied Logic (Miss) ;)

The Boeing thing shows that big Engineering can be really hard, and that in many cases, software is just another unreliable component, somewhat miss-designed and under appreciated (in its failure modes!). The world is eating software, with the usual outcomes.

You could try the technique used in the Git project. Firstly, they do have two two top level `.h` files that are always included as the first lines in any other file that will need includes. This provides a level commonality across the project, and a consistent inclusion order. Secondly, and slightly more important for you, is that all the included `.h` files have a preamble/suffix of:

#ifndef _H
#define _H */

Thus stuff is included only once and a hierarchy of usage is created. Add

#else /* warnings */

for extra feedback and local tastes.

True. It's great oxymoron.

Structural engineering needs the same level of artistry at the top levels, but is close enough to what we think we understand to believe it's "just" the boring application of simple principles, just as coding is. Its worth looking at [1] R. E. Bohn, “Measuring and Managing Technological Knowledge,” in The Economic Impact of Knowledge, Elsevier, 1998, pp. 295–314. doi: 10.1016/B978-0-7506-7009-8.50022-7. Also in HBR and at https://www.researchgate.net/publication/237010832_Measuring_and_Managing_Technological_Knowledge[^] The paper notes how we have a fading level of understanding as we go further away from our own field of understanding. Forth Bridge; Golden Gate; Sydney Opera House ;-)

> Unfortunately, we didn't learn any lessons from it. That's the on thing we could learn ;-)

It's a curse of knowledge thing. The user domain and coder knowledge domains don't overlap, so the user thinks they have full documentation WITHIN THEIR DOMAIN (and they probably do), but that's a world away from from it being transferable knowledge and understanding. Usually, any documentation is some hasty ramshackle bridges from the swampy margins of one domain toward the other, with gaps at the most awkward bits. It's not documented (paved) because almost no one passes that way. It's like finding the old Route 66 (so I'm told). Have you documented your code (rhetorical..) to a level so that the finance folk could debug it?

List them all initially as 'grey', then as the list is parsed/checked change the colour to those for 'working', or 'corrupt'. That way the user is carried along with a little understanding of the apparent 'informative progress bar' style display.

It all depends on whether your (potentially unprofessional) work could kill someone, and how that is "managed" (engineered) with respect to responsibility and control of the work. E.g. the Boeing 737MAX 'software', or the Toyota uncontrolled acceleration, or the London Ambulance service despatch system, or the UK Post Office "Horizon" system (high profile, but few relative to exploding petroleum installations). Software is difficult to characterised with the old 'physical world' mindset where, for example, the electricians' work can be separated from that of the electrical engineers, but in the logical software world, the developer provides the design drawings(code), which is (essentially) the last touch point before final installation. However, very little software is a direct killer of the public, especially if it only manipulates logic and data. So, it's going to take a while before the engineering part is cleanly carved out of software development (cf "just coding").

The white collar/blue collar distinction is interesting. As the software discipline (employment space) expands there becomes a need for gradations in the type and organisation of the work. The vast quantity of mundane software being generated (with occasional gems) tends to a more narrow focus on individual employee capability. Compare this to workers in construction (aka Civil engineering as per brisby's reply) where there are lots of different trades which can be loosely matched to folks from different code camps in terms of particular practical skill sets. With scale comes administration and bureaucracy, and managers. But there is still a need for technical knowledge based competence. Software Engineering is still in its infancy with an academic/R&D overhang. The balance between 'Practical Men' versus 'knowledge and theory' has a long history [e.g. Preece/Heaviside, 1889].

The SKARSTA white, Desk sit/stand, 160x80 cm - IKEA[^] has worked for me - it goes high enough to act as low, medium and 'standing' heights. They are a good price. I hang the PC's Tower case below the desk, using a cheap (pound store) tension strap and plywood base that has a stabilising clamp (Jubilee) to the side leg. I also picked up one of their swivel chairs to help with the back ache/posture (which is usually why a standing desk works well).