Merge pull request #763 from couchbase/writers-guides-updates-sarah-2

The Big Writer's Guide Update

home/modules/contribute/examples/code-blocks.adoc

@@ -1,7 +1,7 @@
 // tag::dl-co[]
 .Optional title
-[source,java] // <1> <2>
----- // <3>
+[source,java]
+---- 
 KStreamBuilder builder = new KStreamBuilder();
 
 KStream<String, GenericRecord> source = builder

home/modules/contribute/examples/description-lists.adoc

@@ -1,26 +1,17 @@
-// tag::basic[]
-Bucket:: A drop-down menu that displays the name of the bucket whose documents are currently being viewed.
-You can use the drop-down menu to select other available buckets.
-Limit:: The maximum number of rows (documents) to retrieve and display at once.
-Document ID:: Accepts the ID of a specific document.
-Leave this field blank to retrieve documents based on *Limit* and *Offset*.
-// end::basic[]
-
-// tag::compound[]
-term 1::
-This description needs two paragraphs.
-To attach them both to term 1, use a list continuation (`+`) on the line separating the paragraphs.
+Bucket:: The top-level data storage container for data in a Capella database. 
+A database can have multiple buckets, but must contain at least 1 bucket before it can store any data.
 +
-This is the second paragraph for term 1.
+For more information about buckets, see Buckets, Scopes, and Collections.
+These sentences appear as a new line for the definition of *Bucket*.
 
-term 2::
-This description includes an admonition block.
-Like additional paragraphs, blocks also need to be connected with a `+`.
+Scope:: A data storage container inside a Capella database. 
+Add scopes to a bucket to organize and group related collections in a Capella database.
 +
-NOTE: An admonition block that is part of term 2's description.
+NOTE: A bucket can only contain a maximum of 1000 scopes.
+This admonition is part of the definition for *Scope*. 
+
+Collection::
+* Collections exist inside scopes.
+.. Create a new collection to store your documents.
+.. This is the final list item. 
 
-term 3::
-* unordered list item
-.. ordered list item
-... another ordered list item
-// end::compound[]

home/modules/contribute/examples/inline-styles.adoc

@@ -1,7 +1,5 @@
 A bold *word*, a *bold phrase*, and bold c**hara**cter**s**.
 
-An italic _word_, an _italic phrase_, and italic c__hara__cter__s__.
-
 A monospace `word`, a `monospace phrase`, and monospace c``hara``cter``s``.
 
-`*_monospace bold italic phrase_*` and ``**__char__**``acter``**__s__**``
+`*monospace bold phrase*` and ``**char**``acter``**s**``

home/modules/contribute/examples/links.adoc

@@ -0,0 +1,5 @@
+https://www.couchbase.com/[The Couchbase Website^]
+
+https://github.com/[]
+
+mailto:[email protected][]

home/modules/contribute/nav.adoc

@@ -1,21 +1,20 @@
 * xref:index.adoc[Overview]
 
 * Setting Up Your Workspace
- ** xref:install-git-and-editor.adoc[Install Git and an AsciiDoc Editor]
- ** xref:install-antora.adoc[Install Antora]
- ** xref:playbook.adoc[Get the Site Playbook Project]
- ** xref:set-up-repository.adoc[Set Up Your Local Repository]
- ** xref:build-site.adoc[Build the Site]
+ ** xref:install-git-and-editor.adoc[]
+ ** xref:install-antora.adoc[]
+ ** xref:set-up-repository.adoc[]
  
 * Contributing Workflow
  ** xref:workflow-overview.adoc[Overview]
- ** xref:repositories.adoc[Repository Organization]
- ** xref:create-branches.adoc[Create a Working Branch]
- ** xref:edit-pages.adoc[Edit Existing Documentation]
- ** xref:add-pages.adoc[Add a New Documentation Page]
- ** xref:update-nav.adoc[Update a Navigation File]
- ** xref:test-site.adoc[Test Changes Locally]
- ** xref:send-pr.adoc[Send Changes for Review]
+ ** xref:repositories.adoc[]
+ ** xref:create-branches.adoc[]
+ ** xref:edit-pages.adoc[]
+ ** xref:add-pages.adoc[]
+ ** xref:update-nav.adoc[]
+ ** xref:playbook.adoc[]
+ ** xref:test-site.adoc[]
+ ** xref:send-pr.adoc[]
 // ** Team Review Process
 // ** Revise Changes
 
@@ -33,7 +32,6 @@
 * Conventions & Styles
  ** xref:component-configuration.adoc[Component Structure and Configuration]
  ** xref:nav-menus-and-files.adoc[Navigation Menus and Files]
- ** xref:style-and-voice.adoc[Content Style and Voice]
  
 * Technical details
  ** xref:generate-rest-api.adoc[]

home/modules/contribute/pages/add-pages.adoc

@@ -1,33 +1,61 @@
-:page-status: OUT OF DATE
-
 = Add a New Documentation Page
 
-NOTE: {out-of-date}
+To add a new page to the Couchbase documentation, you need to create a new AsciiDoc file. 
 
 == Create a New AsciiDoc File
 
-. Start Atom.
-. In Atom's Project panel, navigate to the _pages_ folder in the module where you want to add a new page.
-. Right click on *pages* and select *New File*.
-. Enter a name for the new file in the field.
-The file name becomes the page's URL fragment when it's published to the documentation site.
-** Use lowercase letters.
-** Separate words with hyphens.
-** Don't use symbols or special characters.
-. Add the AsciiDoc file extension, _.adoc_, to the end of the file name, and press kbd:[Enter].
-The new file will open in the editing pane.
-. Enter a xref:pages.adoc#doc-title[document title] on the first line of the file.
+. Open the documentation repository that you want to work in with VS Code. 
++
+TIP: If you enabled the *Open with Code* shortcut when you xref:install-git-and-editor[installed VS Code], you can right-click inside your file explorer window from a repository to quickly open it in VS Code.
+. In the VS Code *Explorer* panel, navigate to the *pages* folder where you want to add a new page.
++
+The folder structure for a documentation repository could look like the following: 
++
+----
+- <component-name>
+ -- modules
+ --- <module-name>
+ ---- assets
+ ---- examples
+ ---- pages
+ ---- partials
+----
++
+Specifically, the folder structure for this component, the `home` component of the Couchbase docs, looks like: 
 +
 ----
-= Title of My Document
+- home
+ -- modules
+ --- contribute
+ ---- assets
+ ---- examples
+ ---- pages
+ ---- partials
+ --- ROOT
+ ---- assets
+ ---- pages
+ ---- partials
 ----
-. Mark up the new documentation with valid AsciiDoc syntax.
-For AsciiDoc help, see xref:basics.adoc[AsciiDoc Basics].
-. Save the file.
+. Right-click the *pages* folder and click *New File*. 
+. Enter a name for your new AsciiDoc file.
+This filename will appear in the page's URL when it's published to our documentation site. 
++
+Make sure your filename: 
++
+** Uses lowercase letters (a-z). 
+** Separates words with hyphens (`-`). 
+** Does not use symbols or special characters, such as `!`, `@`, `#`, or others.
+. End the filename with the AsciiDoc file extension, `.adoc`, and press kbd:[Enter].
++
+VS Code automatically opens the new file. 
+. On the first line of the new file, enter a xref:pages.adoc#doc-title[document title], starting with an `=`.
+. Write your documentation using proper AsciiDoc syntax.
+For more information about AsciiDoc syntax, see xref:basics.adoc[] or https://docs.asciidoctor.org/asciidoc/latest/[the AsciiDoc Language documentation^].
+. Save the file, or take advantage of VS Code's autosave feature (menu:File[Auto Save]).
 
-Any AsciiDoc file that is saved in a _pages_ directory in an Antora documentation component is automatically published to the site.
+Any AsciiDoc file saved to a *pages* directory in an Antora documentation component is automatically published to the site.
 
 == Next Steps
 
 * xref:update-nav.adoc[Add a page to a component navigation menu].
-* xref:build-site.adoc[Build the docs site locally to test and preview your changes].
+* xref:test-site.adoc[Build the docs site locally to test and preview your changes].