Comment by beckford

Comment by beckford 10 hours ago

It is the OCaml language but it also isn't packaged like conventional OCaml. Please don't blame OCaml for that.

It _does_ need a primer for those unfamiliar with OCaml. I was thinking ... since this is scripting ... part of it will probably take the form of a cheat sheet for people coming from Java/C#, JavaScript and Python backgrounds. And another part of it would be how to read an OCaml expression from left to right. Other suggestions welcome.

Direct answers:

- the full explanation of why Std is repeated three times is covered over the first four sections of the first manpage "dk(1)": <https://diskuv.com/dk/help/latest/manual/dk-1/>. It will go over some of the design behind that and also introduce aliases so that "the tool `StdStd_Std.Run` can be typed as `Run`". Did I unnecessarily expose "StdStd_Std" in the introduction?

- the `Tr1Stdlib_V414Io` is a library described in the first reference manual "dkcoder-libraries(7)": <https://diskuv.com/dk/help/latest/manual/dkcoder-libraries-7...>

rfl890 7 hours ago

Thank you for your response. I don't feel that you unnecessarily exposed anything, just that not much explanation was given. Take a look at The Rust Programming Language's "getting started" section[1]. The installation steps are clear, the code is deconstructed and explained, and you are made familiar with the basic CLI tooling. Looking at yours, installation steps are clear, but I'm just given commands and code to paste with no explanation as to what it all does. Sure, I could go browse the man pages, but it's easier to ease into reading manual pages after a gentle beginner's explanation.

Although, given that you mentioned teaching, maybe the page is intended to be presentation-style (less information on the page, more to be explained vocally)? But you can correct me if I'm wrong.

[1] https://doc.rust-lang.org/book/ch01-00-getting-started.html

Reply View 1 reply

beckford 5 hours ago

Yes, there is always verbal instruction (not really explanation) to start with the students. For example, most students I work with don't know how to open a terminal ... they need top-down guidance with copy and paste. The most explanation they would get at the start is that a terminal is where you can copy text and see a response. Pointing them at a web page with directions (mine or others) has never worked for the vast majority of them. The Rust pages in particular... some of them would not understand that they have to press the greater than symbol (>) to go to the next page, and almost all of them would not know they had to strip $ from the commands (or have a clue what Linux is). I think the success rate would be near zero (0%) for that Rust guide without hand-holding. Of course, once they've seen how to do something, they should not need as much handholding.
So eventually we come back and redo the content ... and that becomes the time that explanations are added.
I do like the Rust doc for experienced devs though, although I'll quibble that the doc is not good for Windows users. I'm add a separate explanatory quick start for experienced devs.

Reply View | 0 replies