<img src="https://user-images.githubusercontent.com/15371828/158857061-8fa8d079-d33f-4ed2-88aa-56d452d238d8.svg" alt="DFINITY logo" width="270">

ICP developer portal

The ICP developer portal brings together all the resources needed for developers to build on the Internet Computer. Primarily, this repo hosts the ICP Developer Docs but also includes the Ecosystem Project Showcase, and community tooling page.

The ICP developer portal uses Docusaurus.

This repo is built and deployed using the latest version of dfx (v0.25.0) and moc v0.16.0.

Developer documentation

Repo structure

docs
├── building-apps
│   ├── advanced // advanced development workflows
│   │   ├── optimize
│   │   ├── test
│   │   ├── benchmarking
│   │   ├── using-third-party-canisters
│   ├── authentication // integrate internet identity & alternative origins
│   │   ├── alternative-origins
│   │   ├── integrate-internet-identity
│   ├── best-practices // developer best practices
│   ├── canister-management // canister management and settings
│   │   ├── backtraces
│   │   ├── control
│   │   ├── cycles-wallet
│   │   ├── delete
│   │   ├── history
│   │   ├── logs
│   │   ├── resource-limits
│   │   ├── settings
│   │   ├── snapshots
│   │   ├── state
│   │   ├── storage
│   │   ├── topping-up
│   │   ├── trapping
│   │   ├── upgrade
│   ├── chain-fusion
│   │   ├── bitcoin
│   │   ├── ethereum
│   │   ├── examples
│   │   ├── supported-chains
│   ├── developer-tools
│   │   ├── advanced-dfx
│   │   ├── cdks
│   │   ├── dfx
│   │   ├── dfxvm
│   │   ├── dfx-json-reference
│   │   ├── dfx.json
│   │   ├── icp-ninja
│   ├── essentials
│   ├── frontends
│   │   ├── custom-domains
│   │   ├── asset-security
│   │   ├── existing-frontend
│   │   ├── uploading-serving-assets
│   │   ├── using-an-asset-canister
│   ├── getting-started
│   ├── governing-apps
│   │   ├── nns
│   │   ├── launching
│   │   ├── managing
│   │   ├── testing
│   │   ├── tokenomics
│   ├── interact-with-canisters
│   │   ├── agents
│   │   ├── candid
│   │   ├── advanced-calls
│   │   ├── query-calls
│   │   ├── update-calls
│   ├── network-features
│   │   ├── vetkeys
│   │   ├── signatures
│   │   ├── using-http
│   │   ├── verifiable-credentials
│   │   ├── periodic-tasks-timers
│   │   ├── randomness
│   │   ├── simd
│   │   ├── time-and-timestamps
│   ├── security
├── defi
│   ├── chain-key-tokens
│   ├── rosetta
│   ├── token-indexes
│   ├── token-integrations
│   ├── token-ledgers
│   ├── token-standards
│   ├── create
│   ├── nft-collections
├── motoko // Motoko documentation - submodule
├── references // reference documentation
├── samples // sample projects - submodule
├── tutorials // tutorial series (Developer Liftoff, hackathon prep course, etc).

Contributing to the Dev Docs

Contributions must:

• Must follow the developer docs style guide.
• Must follow the best practices and guidelines.
• Must include document tags.
• Must include SEO keywords.
• Must be in .mdx file format to support the previous two components.
• Must be registered in sidebars.js, otherwise, it will not appear in the side navigation bar.
• New documentation pages that should be owned by a specific team must be added to the .github/CODEOWNERS file to ensure that future pull requests are reviewed by the right people.

If proposed documentation additions do not follow the above guidelines, they will need to be revised.

Additionally, it is recommended to create a branch for changes, then submit a PR that compares the Master branch to your branch. This is because the GitHub preview canister can only generate live previews of proposed changes from branches. It cannot create previews from forks or branches of forks.

Adding a document

To add a new documentation page, first find the category on the sidebar that you'd like to create a new document under. Then, navigate into that subdirectory in the repo and create a new documentation page. See the repo structure outline for more information.

All documents must be in .mdx format.

Format, language choice, and capitalization

Avoid using the terms ‘we’ or 'our' in documentation. Either eliminate using pronouns or instead, use ‘your’.

• “Next, we will open the main.mo file.” → “Next, open the main.mo file.”

• “We need to download dfx before we get started.” → “You need to download dfx before you get started.”

Avoid marketing language and trying to 'sell' the feature. Explain the technology’s benefits in a manner that they should sell themselves to developers.

Follow the Dev Docs Style Guide for guidance on:

• Page structure.
• Use of page headings.
• Use of capitalization.
• Language, spelling, grammar, and word choice.
• Use of punctuation.
• Bulleted lists.
• Bold text.
• Italic text.
• Hints.
• Links and hyperlinks.
• Code snippets and code blocks.
• Command line syntax.
• FAQ sections.

Best practices

When writing documentation for the Dev Docs, the following guidelines should be followed:

Audience

The intended audience of the Dev Docs are existing ICP devs and Web3 blockchain devs who are interested in developing on ICP after they have experience with Ethereum/Solidity, Solana, Bitcoin, etc.

As a more general guideline, the audience can be thought of as the ‘20-29 crypto community’.

This audience should be kept in mind when writing docs. For example:

• When introducing new concepts, tools, and ICP features, assume that the developer will need some additional context. You can provide additional context for other related concepts and features by linking to relevant documents or making mention that the feature builds off of concepts mentioned in another article, then link that article.

• If an ICP-specific term can be related to a broad blockchain concept, use that terminology where it makes sense. For example:

  • Smart contracts on ICP are referred to as canisters.
  • Accounts on ICP are referred to as principals.
  • Multichain applications on ICP use Chain Fusion capabilities.

• When introducing blockchain-specific concepts, it is not necessary to relate concepts to Web2 or traditional programming concepts. It can be assumed that the reader is familiar with blockchain terminology.

Documentation types

The structure and content of the documentation page will vary based on the document type. Some common types are:

Feature or tool detail page

A page that details a specific tool or feature. Feature or tool pages should provide a deeper explanation of a specific feature or tool, why a developer should use it, and how they can use it. It should describe the currently implemented workflows the feature/tool supports, and should not include details of conceptual ideas that are not currently live for developers to use (future roadmap items, possible improvements in the future, etc.)

Concept

Concept pages describe in more detail a specific concept of ICP. Concept pages should relate to broad Web3 terms whenever possible (smart contracts to canisters, accounts to principals, etc.) Concept pages should remain simple and high-level without providing unnecessary, in-depth details. Readers should be able to quickly understand the technology and its benefits, convincing them to continue learning more and begin developing using the technology.

Tutorial

A tutorial uses a step-by-step format to walk a user through a specific workflow. The Developer Liftoff is an example of a tutorial series.

Reference

A reference page provides low level detail into a feature or technology. API reference pages are an example that provide in-depth detail about different endpoints and methods. Some examples include:

Content

Link to resources that go into further detail and provide a brief summary of the concepts within the doc. Some places that may include further details may include additional information:

• The reference technology overview pages

• The how it works section of the website

Try to answer the following questions within the document:

• What is the feature, tool, or concept?
• How do developers benefit from using it? Why should they care about it?
• How can developers use it?
• What dependencies do they need to download or import into their project to use it?
• Are there any best practices they should follow?
• What are the limitations? Are there any nuances they should be aware of?
• What resources or docs should they go to for more information?

Duplication and redundancies

Avoid duplication of content whenever possible. If content exists elsewhere on the Dev Docs that explains the concept or feature you’d like to include, link to that page rather than re-explaining things.

Avoid using several sentences that say the same thing. Remove redundancies whenever possible.

Code snippets

Code snippets should be referenced via their source code files, either from the /docs/references/samples submodule folder or via the file's GitHub URL. For example:

Referenced via submodule file:

	```motoko file=../../../../../submodules/samples/motoko/basic_bitcoin/src/basic_bitcoin/src/Main.mo#L55-L78
	```

Referenced via GitHub URL:

	```motoko no-repl reference
	https://github.com/dfinity/examples/blob/6c9e0a6b6d12978869cbf9ea2943452518909728/motoko/basic_bitcoin/src/basic_bitcoin/src/BitcoinWallet.mo#L49
	```

Simplicity

Keep content as brief and to-the-point as possible. Do not over-explain concepts. Try to use pointed sentences that do not contain ‘fluff’ words.

Keep in mind that developers want to