Updates to contribution guidelines

README.adoc

@@ -53,6 +53,20 @@ For information on writing in AsciiDoc, see:
 There are multiple ways of coding ids, source code blocks, cross-references, and links. In general we use the most explicit coding conventions for coding in order to prioritize code readability. Most of these coding conventions are listed in link:https://redhat-documentation.github.io/asciidoc-markup-conventions/[AsciiDoc Mark-up Quick Reference for Red Hat Documentation]
 ====
 
+== Before you begin
+
+. Install `yarn` if it's not already installed.
+. Install `npx` if it's not already installed.
+. Clone this repo, either from a fork, or if you are an official collaborator, then directly from `starknet-io/starknet-docs`.
+. Change to the `starknet-docs` directory.
+. Run the `yarn` command to prepare the environment:
++
+----
+yarn
+----
+
+`yarn` should prepare your environment by installing the required modules based on `package-lock.json` and `package.json`. If it was successful, you should be able to build and preview content.
+
 == Building and previewing content locally
 
 After writing or editing content, to preview your changes:
@@ -72,7 +86,7 @@ This command generates the website in the directory `public_html`.
 +
 [source,bash]
 ----
-$ http-server public_html -c-1
+$ npx http-server public_html -c-1
 ----
 +
 The server runs, and gives you one or more local URLs that you can use to view the website. For example:
@@ -92,7 +106,8 @@ Hit CTRL-C to stop the server
 
 ----
 
-== Releasing Starknet docs on Github
+== Releasing Starknet docs on Github (for Admins only)
+
 _The high-level process for releasing documentation changes in this repository._
 
 During the course of content development, writers merge branches with changes either directly into `main`, into a secondary branch as needed, where these changes wait until we are ready to release them—that is, post them to link:https://docs.starknet.io[docs.starknet.io].
@@ -115,6 +130,7 @@ Github increments the version numbers in `package.json` and `package-lock.json`,
 starknet-docs (main) git pull
 ----
 * Do a rebase from `git@github.com:starknet-io/starknet-docs.git`:
++
 [source,bash]
 ----
 starknet-docs (main) git fetch origin
@@ -123,6 +139,6 @@ starknet-docs (main) git rebase origin/main
 +
 [NOTE]
 ====
-If you are using a fork, then your forked repo is `origin` by default, in which case you would assign the name `upstream` to `git@github.com:starknet-io/starknet-docs.git`. So when rebasing, use `upstream` instead of `origin` in the above commands.
+If you are using a fork, then your forked repo is `origin` by default, in which case you should assign the name `upstream` to `git@github.com:starknet-io/starknet-docs.git`. So when rebasing, use `upstream` instead of `origin` in the above commands.
 ====
 

contributing_to_docs/doc_guidelines.adoc

@@ -6,11 +6,9 @@
 
 // These guidelines are based on the guidelines for OpenShift documentation. Some sections of the original documentation are commented out. In the future, once it is determined they are not relevant to Starknet docs, those sections might be removed.
 
-== Style guidance and writing guidance
+== Overview
 
-All Starknet documentation should conform to the same rules and guidelines. See the xref:starknet_docs_style_guide.adoc[Starknet documentation style guide].
-
-The rest of this topic details the modular structure and AsciiDoc / Antora requirements and conventions for building Starknet documentation.
+All Starknet documentation should conform to the same rules and guidelines, as detailed below.
 
 toc::[]
 
@@ -33,16 +31,14 @@ link:https://redhat-documentation.github.io/modular-docs/[_Red Hat modular docs
 
 == Style guidance
 
-These _Documentation guidelines_ are primarily concerned with the modular structure and AsciiDoc / Antora requirements for building Starknet documentation. For style guidance, use these style guides in the following order:
+The guidelines on this page are primarily concerned with the modular structure and AsciiDoc / Antora requirements for building Starknet documentation. For style guidance, use these style guides in the following order:
 
 . xref:starknet_docs_style_guide.adoc[_Starknet documentation style guide_] Reference this guide first. It provides guidance that is specific to Starknet documentation.
 . link:https://redhat-documentation.github.io/supplementary-style-guide[_Red Hat supplementary style guide for product documentation_]. This guide overrides certain guidance from the _Google developer documentation style guide_.
 . link:https://developers.google.com/style[_Google developer documentation style guide_]
 
 If you cannot find helpful information or if you must deviate from the guidance in any of these guides, open an issue in the https://github.com/starknet-io/starknet-docs-style-guide/issues[Starknet documentation style guide repo]. The stakeholders can then discuss and determine if and how to address the issue.
 
-toc::[]
-
 == General text editor guidelines
 
 * Set your editor to strip trailing whitespace.