How can we make it easier to experiment with the compiler

[Ola Fosheim Grøstad]

On Tuesday, 25 May 2021 at 11:40:42 UTC, Ola Fosheim Grøstad 
wrote:
> On Tuesday, 25 May 2021 at 11:22:24 UTC, jmh530 wrote:
>> I don't know...I mean it's a start...
>
> Many functions have two-liners documentation already, but it is 
> kinda like a forest. You see lots of individual trees, but the 
> shape of the forest is hard to grasp. More documentation on 
> individual functions won't enable anything. Just like stapling 
> "this is spruce", "this is birch" to individual trees does not 
> help much.

Or let me explain it another way. Assume writing good useful 
documentation takes 10-20% of your coding time.

What should you formally document?

1. High level structure.
2. Stuff that is stable and well encapsulated and needs to be 
explained.
3. FAQs.
4. Functions that deviate from the norm (behaves in surprising 
ways).

Stuff you want to replace, not so much I think. Given that those 
10-20% would be better spent refactoring.