Why oh why are those not comments within the source file? It would help me so much to have comments like those in software...

Generally I think that a linear step-by-step description is often not the best way though, often you would have to explain concepts or the bigger picture first.