Refactor docs folder

CONTRIBUTING.md

@@ -178,8 +178,8 @@ Docs are under [documentation/](documentation/). Refer to the [README.md](docume
 documentation contributions. 
 
 
-[error message style guide]: docs/style-guides/errors.md
-[documentation style guide]: docs/style-guides/docs.md
+[error message style guide]: architecture/style-guides/errors.md
+[documentation style guide]: documentation/README.md#style-guide-for-documentation
 [github help]: https://help.github.com/articles/about-pull-requests/
 [google's open source community guidelines]:
   https://opensource.google.com/conduct/

README.md

@@ -57,7 +57,7 @@ The kpt toolchain includes the following components:
 
 ## Roadmap
 
-You can read about the big upcoming features in the [roadmap doc](/docs/ROADMAP.md).
+You can follow the kpt roadmap in the related [GitHub Project](https://github.com/orgs/kptdev/projects/2/views/2).
 
 ## Contributing
 

documentation/README.md

@@ -33,6 +33,75 @@ The site pulls some dependencies via Git submodules. If `npm install` succeeds b
 git submodule update --init --recursive
 ```
 
+## Style guide for documentation
+
+1. Use US English in the documentation
+
+2. Do not manually add a table of contents to the documents. Hugo and Docsy take care of this.
+
+3. Do not use H1 (#) headers in the documents. Docsy generates an H1 header for every document
+   consistent with the title of the document. Start the headings with H2 (##)
+
+4. Use the built-in alerts for notes and alerts
+
+   ```go-html-template
+   {{%/* alert title="Note" color="primary" */%}}
+   This is a note.
+   {{%/* /alert */%}}
+   ```
+
+   ```go-html-template
+   {{%/* alert title="Warning" color="warning" */%}}
+   This is a warning.
+   {{%/* /alert */%}}
+   ```
+
+5. If you add any commands to the content inline, surround the command with backticks (\` \`), like `ls -la`
+
+6. Do not surround IP addresses, domain names, or any other identifiers with backticks. Use italics
+(\* \*) to mark any inline IP address, domain name, file name, file location, or similar.
+
+7. Whenever possible, define the type of code for your code blocks
+   - \```shell for all shell blocks
+   - \```golang for all Go blocks
+   - \```yaml for all YAML blocks
+   - \```yang for all YANG blocks
+   - a full list of language identifiers is available [here](https://gohugo.io/content-management/syntax-highlighting/#list-of-chroma-highlighting-languages)
+
+
+8. Links to other kpt doc pages should be absolute:
+   - Correct: `[pkg]: /reference/cli/pkg/get/`
+   - Incorrect: `[pkg]: ../../../reference/cli/pkg/get`
+
+9. Flags must appear after positional args:
+
+   - Correct:
+
+   ```shell
+   $ kpt fn eval my-package --image ghcr.io/kptdev/krm-functions-catalog/search-replace
+   ```
+
+   - Incorrect:
+
+   ```shell
+   $ kpt fn eval --image ghcr.io/kptdev/krm-functions-catalog/search-replace my-package
+   ```
+
+10. The name of the tool should always appear as small caps (even at start of
+   sentences) and not in block quotes:
+   - Correct: kpt
+   - Incorrect: `kpt`
+   - Incorrect: Kpt
+   - Incorrect: KPT
+
+11. References to a particular KRM group, version, kind, field should appear with
+   inline quotes:
+   - Correct: `ConfigMap`
+   - Incorrect: ConfigMap
+
+12. Do not add any TBDs to the documentation. If something is missing create an [issue](https://github.com/kptdev/kpt/issues) for it
+
+
 ## License
 
 Licensed under the [Creative Commons Attribution 4.0 International license](LICENSE-documentation)

documentation/content/en/faq.md

@@ -2,7 +2,7 @@
 
 ### What is the roadmap for kpt?
 
-Please visit the [roadmap document] and the [kpt milestones].
+Please visit the [roadmap GitHub Project](https://github.com/orgs/kptdev/projects/2) and the [kpt milestones].
 
 ### How is kpt different from other solutions?
 
@@ -131,8 +131,6 @@ don't have to alias it. It is pronounced "kept".
 [using functions]: /book/04-using-functions/
 [contact]: /contact/
 [functions catalog]: https://catalog.kpt.dev/
-[roadmap document]:
-  https://github.com/kptdev/kpt/blob/main/docs/ROADMAP.md
 [kpt milestones]: https://github.com/kptdev/kpt/milestones
 [kustomize solution]:
   https://github.com/kptdev/kpt/tree/main/package-examples/kustomize