# Documentation Guidelines 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 * Start a topic with Introduction/Concept/Context * 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 lowercase 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. * For work-in-progress features/functions, you may mention the same under the title as shown below:

* Check spelling and grammatical corrections using tools such as Grammarly. ## 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 bold and 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. ## Specification for diagram Follow the below specification while creating diagrams in Miro


Font	Opensans
Font Size	18px
Logos	Use the font available in the URL: https://drive.google.com/drive/folders/1LC9F1WXOKv9xPrC6dHLBFuUG5GOaiPvo?usp=drive_link
Zoom	Default board zoom - 100%. At this zoom level the diagram must fit in a normal screen.
Export image	Size: Medium Format: JPG

## Embed a Miro image To learn how to embed a miro image in the GitBook, [click here](/resources/guides/documentation-guides/documentation-guidelines/embed-a-miro-diagram.md) ## Set an image within the frame in Miro To learn how to set an image within the frame in miro, [click here](broken://pages/XL0xh0UR27BAWjgsRFD2) ## Avoid repetition Do not repeat the content from concept documentation to any other type of documentation and vice versa. Instead, provide the relevant link. Do not repeat the similar content inside the documentation. Instead, provide the relevant link. ## Usage of consistency in words | Use | Do not use | | ------------- | -------------- | | Prerequisites | Pre-requisites | | eSignet | e-Signet | ## Usage of symbols

Document	Symbol
User guide	Click the emoji that appears before the title of the user guide. Type book in the search field and select the encircled symbol The symbol is displayed before the title of the user guide.
Concept	Enter '/' before the title of the user guide that appear at the end of the concept documentation. The below options are displayed. Click the Emoji Type book in the search field Choose the option ":notebook_with_decorative _cover" The symbol is displayed before the title of the user guide.

Document

Symbol

User guide

Click the emoji that appears before the title of the user guide.
Type book in the search field and select the encircled symbol

The symbol is displayed before the title of the user guide.

Concept

Enter '/' before the title of the user guide that appear at the end of the concept documentation.

The below options are displayed.

Click the Emoji
Type book in the search field
Choose the option ":notebook_with_decorative _cover"

The symbol is displayed before the title of the user guide.

## Rules to add link

Use	Do not use
For external end-users, to hyperlink the URLs to access the OpenG2P system, Use a generic URL to hyperlink. For example, the end-users organisation specific URLs after their installation of OpenG2P system.	For external end-users, to hyperlink the URLs to access the OpenG2P system, Do not hyperlink the internal URLs. For example, the environment-specific URLs such as test, dev, QA, stage, and so on.

Use

Do not use

For external end-users, to hyperlink the URLs to access the OpenG2P system,

Use a generic URL to hyperlink. For example, the end-users organisation specific URLs after their installation of OpenG2P system.

For external end-users, to hyperlink the URLs to access the OpenG2P system,

Do not hyperlink the internal URLs. For example, the environment-specific URLs such as test, dev, QA, stage, and so on.

--- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.openg2p.org/resources/guides/documentation-guides/documentation-guidelines.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.