doc/README: suggest a way to preview next content, tweak release steps

Smaller edits are usually fine to do without previewing, since Markdown
can be intuitive. But for larger changes including re-ordering sections
and such, it can be helpful to quickly see the end result. Write down a
way to do that.

Update the release steps to capture that the doc/next content will move
to x/website before RC 1, when the complete release note draft is ready.

For #64169.

Change-Id: Ie554ed5294ce819fd0689e2249e6013826f0c71f
Reviewed-on: https://go-review.googlesource.com/c/go/+/587922
Reviewed-by: Dmitri Shuralyov <dmitshur@google.com>
Auto-Submit: Dmitri Shuralyov <dmitshur@golang.org>
TryBot-Bypass: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Jonathan Amsterdam <jba@google.com>

diff --git a/doc/README.md b/doc/README.md
index 3d0fb861029cde1ba7db5a677eee2967a9f4d8ec..bfd3c1e6a1b31c2a5d3a27aca85faede114026c0 100644 (file)
--- a/doc/README.md
+++ b/doc/README.md
@@ -41,9 +41,18 @@ Use the following forms in your markdown:
 
        [http.Request]                     # symbol documentation; auto-linked as in Go doc strings
        [Request]                          # short form, for symbols in the package being documented
+       [net/http]                         # package link
        [#12345](/issue/12345)             # GitHub issues
        [CL 6789](/cl/6789)                # Gerrit changelists
 
+To preview `next` content in merged form using a local instance of the website, run:
+
+```
+go run golang.org/x/website/cmd/golangorg@latest -content='' -goroot=..
+```
+
+Then open http://localhost:6060/doc/next. Refresh the page to see your latest edits.
+
 ## For the release team
 
 The `relnote` tool, at `golang.org/x/build/cmd/relnote`, operates on the files
@@ -54,12 +63,13 @@ unfinished release note work.
 
 To prepare the release notes for a release, run `relnote generate`.
 That will merge the `.md` files in `next` into a single file.
+Atomically (as close to it as possible) add that file to `_content/doc` directory
+of the website repository and remove the `doc/next` directory in this repository.
 
-To begin the next release development cycle, delete the contents of `next`
-and replace them with those of `initial`. From the repo root:
+To begin the next release development cycle, populate the contents of `next`
+with those of `initial`. From the repo root:
 
     > cd doc
-    > rm -r next/*
     > cp -r initial/* next
 
 Then edit `next/1-intro.md` to refer to the next version.