Improvements to the manual

[ry]

WebAssembly

• Link to MDN sources
• Provide Rust program that compiles to provided bytes
• Write about instantiateStreaming currently not supported

TypeScript

• Make a separate chapter

IO model

• How IO work in Deno
• comparison with ReadableStream, WriteableStream
• how to convert to/from ReadableStream

Comparison with Node.js

• Make a separate chapter
• Compare most common Node APIs with Deno equivalents
• Write about popular Node packages that are built into Deno

Plugins

• Link to example plugin
• Basic "fetch.js", deno_core::explanation

Examples

• Move higher in the menu order

Tools

• Move “Debugger” to “Debugging your code” in “Getting started”
• Bundler - point out “for await of” does not work, it is an upstream bug, provide a workaround (ie. async iffe)

Deploying your code

• Bundle it
• How to setup basic CI
• Best practices

Architecture

• Draw new diagram
• Link to @ry’s talk about deno structure from Israel meetup https://www.youtube.com/watch?v=1b7FoBwxc7E

Building from source

• Update

• Style guide - ask @piscisaureus to update it

• Provide special markers for Deno version and corresponding std version and automatically insert in all examples - eg. $DENO_VERSION$/$STD_VERSION$

• Links to API reference, std library should be visible on every page of the manual

Testing

• how tests are registered
• processing order
• concurrency

Std:

• All imports in readme examples should be versioned, and bumped on release

[caspervonb]

Been intending to update the WebAssembly page of the manual, I'll get on that part.

[David-Else]

The biggest omission is a search bar, it is impossible to find what you are looking for.

[nayeemrmn]

@David-Else That's a website issue.

[David-Else]

@nayeemrmn Somewhat of a semantic issue when the 'manual' only exists as a website :)

[nayeemrmn]

@David-Else No? The docs directory in the main repo contains markdown files which comprise the manual. That's what this issue is about. You're talking about the website's presentation of it.

[David-Else]

@nayeemrmn I agree with you technically, I was just looking at it from a user perspective and making the point 'the manual' and the 'manual on the website' are the same thing for most people.

I was also keen to point out there is not much point in fantastic docs with no search, which in retrospect was off-topic, so sorry about that.

[caspervonb]

Search is a valid issue, but should be over at the presentation side https://github.com/denoland/deno_website2

[lucacasonato]

The biggest omission is a search bar, it is impossible to find what you are looking for.

We're working on it.

[RobDWaller]

Question on examples section do we think it should be broken down into basic and advanced?

Currently most of the examples strike me as advanced, for instance the cat example rests on the assumption you know what cat does. It's a good example but to many junior developers it may as well be entitled An implementation of the unix "tac" program.

A basic example might be something like, "How to read a JSON file". I'm sure we could come up with 8 basic examples to go along with the current examples?

[David-Else]

@RobDWaller I agree we need more basic topics covered, but I think the problem is more nuanced than just adding more examples. In the cat example:

The copy() function here actually makes no more than the necessary kernel -> userspace -> kernel copies. That is, the same memory from which data is read from the file, is written to stdout. This illustrates a general design goal for I/O streams in Deno.

The actual example is basic, but then it immediately goes into advanced subjects with no references to enable users to look up the required info to understand the concepts. My thoughts on the above sentence:

• What is a kernel to userspace copy?
• What is the kernel refering to in this context, the linux kernel?
• What is meant by userspace?
• What is the 'necessary' amount of copies vs an approach that might use too many?
• What is stdout?
• What are streams?
• How does this illustrate an I/O streams design goal? Why do I care about a design goal in my first deno example program?

This is the first example that the user clicks on. It may be the very first page of the manual that the user clicks on. Immediately in one single sentence, they are expected to know about kernel, userspace, stdout, and streams. These topics should have a section where they are briefly explained and inline links provided in the example text.

[ry]

Good points. I think it was the first and only example for a while. I'm open to reordering them.

[RobDWaller]

I've started writing up some basic examples and I should have it finished by next week.

https://github.com/RobDWaller/deno-basic-examples

Hopefully it will be acceptable and can form a good set of basic examples which will help new developers get going with Deno. Once I've done this I'm happy to move onto expanding the advanced examples.

I've kept it as a separate repo for now so I don't pollute the Deno repo with lots of changes, will transfer it over if people are happy with the finished product.

[RobDWaller]

So I've created a draft pull request for the examples documentation changes, if the basic format is acceptable I will submit it for formal review. Let me know your feedback.

#6958

[ebebbington]

Regarding a FAQ, i think it would be good front and center, for example as a new li item in the website header. And maybe even a readonly #FAQ channel in the discord that links to the FAQ, so it's a breeze for users to navigate to it, and makes it highly visible

[gSarciotto]

What is needed in the typescript chapter?

[Bromeon]

Based on some discussion in Discord, it looks like several people are looking for guidance for calling Javascript code from Rust, and this is rather complex given the current API. If appreciated, I could gladly write some examples for simple use cases such as the following ones:

• Executing a JS script from Rust
• Printing some basic things (as console.log does not work)
• Passing parameters (Rust -> JS) and return values (JS -> Rust)
• Evaluating a JS expression in Rust

[tokiedokie]

Link to @ry’s talk about deno structure from Israel meetup https://www.youtube.com/watch?v=1b7FoBwxc7E

This is done in #6859

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[chances]

@ry Which of this issue's other bullet points are still unaddressed?

[ebebbington]

And that is why I dislike the stale bot

[bartlomieju]

I added issues in https://github.com/denoland/manual repository with chapters that are still missing