From b17e10c72e956fb00efa2eabfbeaa455a9e8148d Mon Sep 17 00:00:00 2001
From: Delyan Angelov <delian66@gmail.com>
Date: Sun, 31 May 2020 08:42:34 +0300
Subject: [PATCH] docs: mention `v run` and `v symlink` earlier

---
 README.md   | 29 +++++++++++++++++++++++++++--
 doc/docs.md | 16 +++++++++++++---
 2 files changed, 40 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index b578c44984..375b6e1e01 100644
--- a/README.md
+++ b/README.md
@@ -49,10 +49,14 @@ cd v
 make
 ```
 
-That's it! Now you have a V executable at `[path to V repo]/v`. `[path to V repo]` can be anywhere.
+That's it! Now you have a V executable at `[path to V repo]/v`. 
+`[path to V repo]` can be anywhere.
 
 (On Windows `make` means running `make.bat`, so make sure you use `cmd.exe`.)
 
+After the above, you can try doing: `./v run examples/hello_world.v` on Unix, 
+or `.\v.exe run examples\hello_world.v` on Windows.
+
 V is being constantly updated. To update V, simply run:
 
 ```
@@ -71,12 +75,33 @@ Otherwise, follow these instructions:
 
 ### Symlinking
 
-You can create a `/usr/local/bin/v` symlink so that V is globally available:
+NB: it is *highly recommended*, that you put V on your PATH. That saves
+you the effort to type in the full path to your v executable everytime.
+V provides a convenience `v symlink` command to do that more easily.
+
+On Unix systems, it creates a `/usr/local/bin/v` symlink to your
+executable. To do that, run:
 
 ```bash
 sudo ./v symlink
 ```
 
+On Windows, start a new shell with administrative privileges, for 
+example by <Windows Key>, then type cmd.exe, right click on its menu
+entry, and choose `Run as administrator`. In the new administrative 
+shell, cd to the path, where you have compiled v.exe, then type:
+```bat
+.\v.exe symlink`
+```
+That will make v available everywhere, by adding it to your PATH. 
+Please restart your shell/editor after that, so that it can pick 
+the new PATH variable.
+
+NB: there is no need to run `v symlink` more than once - v will 
+continue to be available, even after `v up`, restarts and so on. 
+You only need to run it again, if you decide to move the V repo 
+folder somewhere else.
+
 ### Docker
 
 <details><summary>Expand Docker instructions</summary>
diff --git a/doc/docs.md b/doc/docs.md
index 36ea81c9e6..eb994544ed 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -91,10 +91,20 @@ fn main() {
     println('hello world')
 }
 ```
+Save that snippet into a file `hello.v` . Now do: `v run hello.v` .
 
-Functions are declared with `fn`. The return type goes after the function
-name. In this case `main` doesn't return anything, so the return type can be
-omitted.
+(That is assuming you have symlinked your V with `v symlink`, as described here
+[Symlinking](https://github.com/vlang/v/blob/master/README.md#symlinking).
+If you have not yet, you have to type the path to v/v.exe manually.)
+
+Congratulations - you just wrote your first V program, and executed it!
+
+(You can compile a program without execution, with: `v hello.v`.
+See `v help` for all supported commands)
+
+In the above example, you can see that functions are declared with `fn`.
+The return type goes after the function name. In this case `main` doesn't 
+return anything, so the return type can be omitted.
 
 As in many other languages (such as C, Go and Rust), `main` is an entry point.