Documentation styleguide
This guide outlines the standards for creating ZKsync documentation, ensuring consistency in writing style, Markdown conventions, and code snippets.
Writing Style
For readability across a diverse audience, including non-native English speakers, we adhere to industry best practices from:
It's crucial to create content that is inclusive, diverse, and timeless. Focus on:
Spelling
Content in ZKsync Docs are run through a linter for markdown formatting and spellchecking.
Some words may not pass the spellcheck linter and will need to be added to the dictionary list.
New words can be added to lists in /cspell-config. All words added to the dictionary are checked
for spelling only.
Time & Dates
To minimize confusion due to global date format variations, adhere to the following in ZKsync docs:
- Start calendars on Mondays.
- Use the date format
month dd, yyyy, avoiding numerals for months (e.g., January 5, 2018).
Types of documentation
Following the Diataxis framework, ZKsync Docs categorizes content into
- Tutorials: Step-by-step instructions to teach general skills (e.g., Deploying your first contract on ZKsync Era).
- Guides: Task completion instructions for readers with basic knowledge (e.g., Debugging with zksync-cli).
- References: Detailed technical descriptions (e.g., Ethereum JSON-RPC API).
- Explanation: Content to deepen subject understanding (e.g., Differences between ZKsync Native Account Abstraction and Ethereum's EIP 4337).
Choosing a category
Leverage the Diataxis system when crafting a new article for ZKsync Docs. Writing without a clear category often results in unfocused content. A well-defined focus keeps the content streamlined and clarifies the takeaway for the reader.
While adhering to this system, it may become evident that a single article cannot encompass all aspects you wish to convey. Feel encouraged to create multiple articles across different categories to comprehensively address your topic.
Add new documentation
To add new pages to our documentation, create new files under the /content directory.
Naming scheme
File and folder names are prefixed with a number that Nuxt uses to handle what order pages are displayed in navigation. We use a two-digit numbering system to allow for easier re-ordering of files.
If you are creating a new directory, name your first file 00.index.md.
This ensures there is a root path to the page.
The display name will be defined by the title in the frontmatter.
_dir.yml
The _dir.yml allows for further configuration of the directory.
The title defined in this file is what defines the header for the dropdown panel in navigation.
Frontmatter
All pages must have frontmatter with a title and description.
If you do not want a description for your page, simply leave the description value blank.
Images
Add images to the public/images/ directory to use in ZKsync docs
and reference them from the /images path, do not include the public/.
Use the markdown format to display images.
- Keep your image size to 600-960px wide.
- If you are displaying visual diagrams with text, use svg format for best clarity.
- Avoid using images to display only text, code or data output, use actual text.
- Every image should have a descriptive alt text.
- Optimize your image using a service like TinyPNG.
Icons
Utilize Nuxt UI icons with the UIcon component, following the naming pattern i-{collection_name}-{icon_name}.
The icon collections pre-configured for this project are heroicons, simple-icons, devicon and logos.
You can browse the icons available in each collection on Icones. This browser is also available from the Nuxt Debug tools.
:u-icon{name="i-heroicons-light-bulb"}
Links
Internal links are generated in relation to the /content directory and the name of the markdown file.
For example, the file /content/1.quick-start/2.deploy-contract.md is defined as the path /quick-start/deploy-contract.
Do not add the number or file extension on the link.
Example link to an internal page using markdown format, with an anchor tag.
[Getting Started](/zksync-era/guides/zksync-101#install-docker)
Markdown and Vue components
ZKsync Docs combine Markdown with Vue components though the syntax is different. For example, if you use a Nuxt UI Button component, the html syntax would be the following:
<UButton color="primary" variant="solid">
I am a button
</UButton>
In markdown, the syntax changes to the following:
::u-button{ color="primary" variant="solid" }
I am a button
::
If the Vue component is an inline slot-less component, you can use a simplified inline format.
<UButton label="Button" />
<!-- format in markdown -->
:u-button{ label="button" }
Learn more about using Markdown and Vue components with Nuxt Content's page on Markdown.
Content Switcher
For content organization into tabs, utilize the ContentSwitcher component.
Apply the items prop to distribute content across tabs.
Organize these partials in a folder that matches the parent markdown file’s name,
preceded by an underscore.
Use the Content Switcher component in a situation where you have more than one option to display for a subject depending on the reader's choices. For example, use the Content Switcher component for a tutorial that provides a Remix and Atlas option.
::content-switcher
---
items: [{
label: 'HardHat',
partial: '_getting-started/_aPartial'
}, {
label: 'Forge',
partial: '_getting-started/_anotherpartial'
}]
---
::
Callouts
Callouts present warnings, extra detail, or references to related topics. A callout should not contain anything essential to understanding the main content.
Example
callout with full markdown support. It can have markdown content like a link to another page.Code
::callout{icon="i-heroicons-exclamation-triangle" color="amber"}
This is a `callout` with full **markdown** support. It can have markdown content like a link to [another page](/zksync-era/guides/zksync-101).
::
Code Samples
Use code samples where it helps to explain technical concepts. Create concise examples that are easy to read and understand, avoid pasting an entire file of code. Always define the language the code is represented in next to the backticks. Additionally, you can define the name of the file to display as a header on the block.
Example
export default defineNuxtConfig({
extends: ['@nuxt/ui-pro'],
modules: ['@nuxt/ui']
})
Code
```ts [nuxt.config.ts]
export default defineNuxtConfig({
extends: ['@nuxt/ui-pro'],
modules: ['@nuxt/ui']
})
```
Localization
Currently, ZKsync Docs does not offer localized documentation. Updates to this section will be provided as localization features become available.
Use of AI
While fully AI-generated content is not accepted for ZKsync Docs, the assistance of AI tools like ChatGPT in editing content is permitted. These tools can enhance the editing process, although they may occasionally produce inaccurate information. Always carefully review any AI-assisted content before finalizing.
You can use the following as a prompt for an AI tool to help with editing:
The content is written in common markdown format.
Use the Google Developer Documentation Style Guide and the Microsoft Style Guide, emphasizing Bias-free communication.
Write in an active voice.
Do not use the definite or indefinite article with “ZKsync Era”.
Assume the reader may be an international person whose first language might not be English.
Don’t use overly complex words unless the technical description is lost if changed.
Ensure all communication is bias-free, following the Microsoft Style Guide's directives for inclusiveness and fairness in language.
If the article I submit has a Header1 at the beginning, move that into a yaml frontmatter for the 'title' property.
Include a short description of the article in the yaml frontmatter in the 'description' property.
If your content includes technical descriptions and code examples, you can add the following to your prompt to assist with formatting.
Always use the word “function” and never the word “method” when referring to Solidity code.
Always use the word “function” for functions in JavaScript and TypeScript.
Always use the word “method” for attributes of an object in JavaScript and TypeScript.
When talking about Rust, always use the word “function” for functions defined on a type, and the word “method” for functions defined on an instance of a type.
When referring to a JSON RPC URL method, always use the word “method”.