As Ark originates from an online community, different writing styles have been used in formal and community writings. It is important to have a uniform style across our documentation to avoid misunderstandings and provide consistency to developers.

Writing documentation is quite simple, often the last 10% of a project. Regardless the last 10% can consume 90% of the effort. Proper documentation requires fluency in English and a well thought out objective. Ark's documentation is written for the semi-knowledgeable. However, beginners should be able to follow most of the tutorials and learn from the docs. Well documented, average software is more usable than poorly documented, fantastic software.

Ark's official language is American English, which is used in nearly all writings. This conforms to most technical documentation and writings, as often programming languages adhere to American English as well.

Use a clear, semi-formal tone in writing. There is no need to go as far as academic writing, but keep the following in mind:

Long sentences without an objective are confusing. There is no need to use extra adjectives to increase sentence length or illustrate a concept. Remember that just as with code; documentation comes with a burden of maintenance.

Reuse definitions. In fintech and blockchain, we often use words such as blocks, transactions, crypto. While writing documentation, the use of these definitions might seem repetitive; however, these are familiar concepts and leave little room for interpretation to the reader.

Grammar is important. It reflects the professionalism of the entire project.

Use proper punctuation, in tables, captions, and citations. Titles should use title casing.

In tutorials and descriptions, we often have code snippets present to illustrate SDK functionalities. If you provide a code snippet, showing how to use a function, ensure that the reader knows what has been omitted. Start a tutorial with the setup code, imports, and installations before the main body. Ensure the code uses correct namespaces. When documenting a library, use the library as if you were an end-user:

Do not use the following:

client :=New()

However, instead:

package main
import"my/lib/name"funcmain(){
client := name.New()}

In following snippets, the package and import declarations may be omitted. Avoid using ... to indicate an omitted fragment; it should be apparent to the reader without such indicators.

If a code snippet is relevant in multiple languages, create tabs for all languages, even if you do not intend to write the code snippet in the other languages. This makes it very obvious to the reader and us that the documentation needs to be improved/updated. Tabs should be ordered as follows:

Javascript is placed in the front, as it is widely used, and the primary language used in Ark.

Java is often used by exchanges and institutions and remains one of our most widely used SDKs.

Bittrex is built on top of the .NET stack, and just as with Java, C# is also used within companies.

PHP is a conventional programming language. We also support two dedicated PHP frameworks.

Python is an academic language. Ark aims to collaborate with Universities and researchers.

Go is the language of the distributed stack, and many blockchain developers are familiar with it.

The Bitcoin protocol was written using C++, need I say more?

Ruby, powered by Rails, is a great tool for developing backends.

Apple's official language. Currently not used in the Ark mobile wallet.

A tab may contain a code snippet, but also language-specific explanations. Attempt to keep each tab the same size, to avoid screen jumps when the user switches between tabs.

When using a bash command, prepend the command with $ only if the output is shown as well. The terminal output should be put inside a code block, not added as a screenshot. In general, text should remain text.

There are many terms commonly used when describing aspects of Ark and related technologies. To standardize how documentation is presented to the user and to remove differences across different texts, we have established the following rules for using Ark terminology.

When talking about Ark's native currency, you MUST refer to it as ARK - it is commonly used as the currency ticker on exchanges and within Ark Ecosystem projects like the Ark Desktop Wallet and Ark Explorer. The currency symbol for ARK is "Ѧ". It can be represented with the decimal Unicode 1126 or "&#1126;" in HTML.

Generic terms like "address", "wallet", "transaction", "delegate", "vote", "blockchain", "currency" SHOULD NOT be capitalized, alongside the three above terms which mainly refer to concepts and not necessarily rigid implementations.

The scopes of each category might change to include or exclude new or old concepts at any given time, due to the continually evolving Ark (Ecosystem) landscape.

Although it would be ideal, not all documents can afford only to mention Ark's projects and concepts.

We encourage you always to follow other projects' standards for writing about them when you mention them in a document:

The Ark blockchain was created later than the Bitcoin blockchain

In addition, please refrain from capitalizing terms like "blockchain", as it would imply some unencouraged buzz-wordiness.

An essential part of documenting for the open source Ark Ecosystem is to offer the reader an unintrusive option to go to another branch of resources and learn without breaking the underlying reading experience.

It is acceptable to link once to Ark Ecosystem or other technological projects mentioned in the document you write unless mentioned in succession within a list. Linking the first occurrence of a technical project mention is good practice.

Additionally, you are encouraged to provide a list of references at the end of your written document. This helps streamline the user's experience when wanting to read resources on the aforementioned projects without having to scroll back through the material.

To provide an easy to access and clean reference to a website, especially when dealing with websites external to the Ark Ecosystem, the writer MUST include a link to the URL with an appropriate name rather than the plain, unclickable, URL.

As an essential part of online documentation, images must be used with respect to licensing rights and other ethical considerations.

To unify the look and feel of the documentation, images or other branded content available and relevant to your document SHOULD be included.

If writing a document for an Ark project, like the Ark Mobile Wallet, you MUST use the official banner image for it (located on GitHub) at the start of the document.

When needing to use official Ark imagery, you may find suitable media assets at ark.io/mediakit. Otherwise, you are encouraged to design your images, use external images with proper attribution in as references or outsource the graphical design task to someone else.

When writing technical guides; do not take screenshots of the console. Add the textual output from commands as code snippets, either using the bash tag or omitting the tag altogether. Screenshots are difficult to update, requiring the maintainers to go through the guide step-by-step.