From f5d98cbaa8602a31bdd7492d37ea998cfa5b4f60 Mon Sep 17 00:00:00 2001 From: Puneet Joshi Date: Fri, 5 Jan 2024 05:05:20 +0000 Subject: [PATCH] GITBOOK-73: No subject --- SUMMARY.md | 2 +- .../documentation-guides/creating-diagrams.md | 61 ------------------- .../documentation-guidelines.md | 28 +++++++++ 3 files changed, 29 insertions(+), 62 deletions(-) delete mode 100644 guides/documentation-guides/creating-diagrams.md create mode 100644 guides/documentation-guides/documentation-guidelines.md diff --git a/SUMMARY.md b/SUMMARY.md index 2c8241f5..3714f915 100644 --- a/SUMMARY.md +++ b/SUMMARY.md @@ -166,9 +166,9 @@ * [Submit Reimbursement Using the Service Provider Portal](guides/user-guides/submit-reimbursement-using-the-service-provider-portal.md) * [Reimburse the service provider](guides/user-guides/reimburse-service-provider.md) * [Documentation Guides](guides/documentation-guides/README.md) - * [Creating Diagrams](guides/documentation-guides/creating-diagrams.md) * [OpenG2P Module Doc Template](guides/documentation-guides/openg2p-module-doc-template.md) * [Writing Guidelines For How-To Guides](guides/documentation-guides/writing-guidelines-for-how-to-guides.md) + * [Documentation Guidelines](guides/documentation-guides/documentation-guidelines.md) * [Deployment Guides](guides/deployment-guide/README.md) * [Deployment on Kubernetes](guides/deployment-guide/deployment-on-kubernetes/README.md) * [K8s Cluster Requirements](guides/deployment-guide/deployment-on-kubernetes/k8s-cluster-requirements.md) diff --git a/guides/documentation-guides/creating-diagrams.md b/guides/documentation-guides/creating-diagrams.md deleted file mode 100644 index 218b0a22..00000000 --- a/guides/documentation-guides/creating-diagrams.md +++ /dev/null @@ -1,61 +0,0 @@ -# Creating Diagrams - -## Context - -Creating editable diagrams in open formats using open source tools is challenging. Here, we suggest [Draw.io](https://app.diagrams.net/) for creating diagrams and saving them directly in GitHub repository. - -## Creating new diagram - -1. On [Draw.io](https://app.diagrams.net/) website choose _Device_ as your storage. - -
- -2. Select the format of the diagram as XML`.drawio.` - -
- -3. Create the diagram and save it on your local machine. Make sure you follow the file naming convention of lowercase with hyphens as word separations. -4. Fork `openg2p-documentation` repository to your Github account. -5. Disable workflow in your repository fork: - -
- -6. On Github, upload/commit the `.drawio` file to **your fork** of `openg2p-documentation` repository in the branch of choice to the following folder: `.gitbook/assets`. -7. Send a Pull Request. -8. After the PR is merged on the upstream repo a [Gitbook Action Workflow](https://github.com/OpenG2P/openg2p-documentation/blob/1.2/.github/workflows/drawio.yml) will get triggered to convert the same to PNG format with `*.png` extension. The PNG file will be available in the same folder as the `.drawio` file. In this case, it will be the repository's `.gitbook/assets` folder. -9. On Gitbook, insert the PNG image using the _URL_ options shown by Gitbook. The URL to be given will be the GitHub URL e.g. [https://github.com/OpenG2P/openg2p-documentation/raw/1.2/.gitbook/assets/add-deduplication-manager.png](https://github.com/OpenG2P/openg2p-documentation/raw/1.1/.gitbook/assets/add-deduplication-manager.png). Make sure you pick this URL in **Raw** format which will be available on the _Download_ button on Github - -
- -## Editing existing diagram - -If a `.drawio` already exists in the `.gitbook/assets` folder then you must directly edit the repository version of the same by following the procedure given below. - -1. Fork the `openg2p-documentation` repository to your local Github account. Disable workflow as shown above. -2. On the [Draw.io](https://app.diagrams.net/) website choose Github as your storage. - -
- -3. Authorize the Draw.io app on Github (follow the steps prompted). -4. Select the diagram in `.drawio` format from `openg2p-documentation` --> your branch --> `.gitbook/assests` folder. - -
- -5. Make changes. -6. Save the diagram - it will get Git-committed to your repository. -7. Send a Pull Request to `OpenG2P/openg2p-documentation` repo. -8. Upon acceptance of the Pull Request, a [Github Action Workflow](https://github.com/OpenG2P/openg2p-documentation/blob/1.2/.github/workflows/drawio.yml) will trigger the conversion of the`.drawio` file to `.png`. -9. If you have not added the URL of the PNG to your Gitbook pages follow step 6 of [Creating New Diagram](creating-diagrams.md#creating-new-diagram). -10. If the URL already exists in Gitbook, the updated image should appear after a page refresh. - -## Deleting a digram - -1. Delete the diagram from Gitbook listing found here: - -
- -
- -
- -2. Delete the diagram from Github repository `openg2p-documentation` from the corresponding branch diff --git a/guides/documentation-guides/documentation-guidelines.md b/guides/documentation-guides/documentation-guidelines.md new file mode 100644 index 00000000..e411e71d --- /dev/null +++ b/guides/documentation-guides/documentation-guidelines.md @@ -0,0 +1,28 @@ +# Documentation Guidelines + +## Introduction + +This guide provides basic guidelines for you to write neat documentation. + +## General conventions + +* Page title: Capitalize the first letter of every word. Like this page title +* Check spelling and grammatical corrections using tools such as Grammarly. +* Use Gitbook's "Heading 1, Heading 2" etc for headings +* Headings must use lowercase except for the first letter. E.g. "Code of conduct" +* Provide reference links to the text as applicable. +* Provide a link at the first mention of a new/different topic. For example, if the guide is talking about installing the SmartScanner app, and the WireGuard app is mentioned, then provide the link for WireGuard. +* Avoid using ":" in a heading. E.g. "Design choices:" +* Use clear and crisp images - the images should not appear blurred when seen on full screen. +* If you are adding image files, make sure all file names are lower case with hyphens. E.g `architecture-diagram.png`. +* The filename for images should follow the naming convention of every word in lower case, and words separated by hyphens i.e. view-all-programs.png. + +## User guides + +In addition to the above while writing user guides follow these conventions: + +* Use second-person pronouns i.e. you, your, etc. in the instructions/steps. +* Use the italicized font for UI elements i.e. dashboard names, button labels, information fields, etc. +* Use the exact name and case for the UI elements as shown in the user interface. +* Use quotes for a phrase/word if the phrase/word has to be represented as is. +*