[draft] ICP Dev Docs Restructure, Overhaul & Audit

.github/CODEOWNERS

@@ -1,22 +1,23 @@
 .github/ @dfinity/idx
 * @dfinity/editorial
 
-docs/developer-docs/updates/release-notes/ @dfinity/dx
-docs/developer-docs/build/agents @dfinity/dx
-docs/developer-docs/build/cdks @dfinity/dx
-docs/developer-docs/integrations/rosetta @dfinity/finint
-docs/developer-docs/security @dfinity/product-security
+docs/other/updates/release-notes/ @dfinity/dx
+docs/building-apps/interact-with-canisters/agents/overview @dfinity/dx
+docs/building-apps/developer-tools/cdks/index @dfinity/dx
+docs/defi/ @dfinity/finint
+docs/concepts/security @dfinity/product-security
 docs/references/execution-errors.mdx @dfinity/execution
-docs/references/ingress-messages.mdx @dfinity/product-security
-docs/references/message-execution-properties.mdx @dfinity/product-security
-docs/developer-docs/web-apps/custom-domains @dfinity/boundary-node
-docs/developer-docs/web-apps/http-compatible-canisters @dfinity/trust
+docs/building-apps/interact-with-canisters/advanced-calls.mdx @dfinity/product-security
+docs/concepts/message-execution/message-execution-properties.mdx @dfinity/product-security
+docs/building-apps/frontends/custom-domains/ @dfinity/boundary-node
+docs/building-apps/network-features/using-http/http-certification/ @dfinity/trust
 
 # Each piece of documentation must be owned by the respective teams
-docs/developer-docs/smart-contracts/advanced-features/simd.mdx @dfinity/execution
-docs/developer-docs/smart-contracts/advanced-features/periodic-tasks.mdx @dfinity/execution
-docs/developer-docs/smart-contracts/best-practices/idempotency.mdx @dfinity/research @dfinity/product-security
-docs/developer-docs/smart-contracts/maintain/backtraces.mdx @dfinity/execution
+docs/building-apps/network-features/simd.mdx @dfinity/execution
+docs/building-apps/network-features/periodic-tasks-timers.mdx @dfinity/execution
+docs/building-apps/best-practices/idempotency.mdx @dfinity/research @dfinity/product-security
+docs/building-apps/canister-management/backtraces.mdx @dfinity/execution
+
 
 # The Interface Specification
 docs/references/_attachments/certificates.cddl @dfinity/canister-os

.github/workflows/docs-check.yml

@@ -3,7 +3,10 @@ on:
   issue_comment:
     types: [created]
     paths:
-      - docs/developer-docs/
+      - docs/concepts
+      - docs/building-apps
+      - docs/defi
+      - docs/specifications
 
 jobs:
   check_comment:

.github/workflows/docs-tag.yml

@@ -2,7 +2,11 @@ name: Tag Docs PRs
 on:
   pull_request:
     paths:
-      - docs/developer-docs/**
+      - docs/concepts/**
+      - docs/building-apps/**
+      - docs/defi/**
+      - docs/tutorials/**
+
 jobs:
   docs-tag:
     name: Tag PR with documentation

README.md

@@ -3,7 +3,7 @@
 # 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](https://internetcomputer.org/docs/current/home) but also includes the [Ecosystem Project Showcase](https://internetcomputer.org/ecosystem), [community tooling page](https://internetcomputer.org/tooling), and the internetcomputer.org ['How it works'](https://internetcomputer.org/how-it-works) series.
+Internet Computer. Primarily, this repo hosts the [ICP Developer Docs](https://internetcomputer.org/docs/home) but also includes the [Ecosystem Project Showcase](https://internetcomputer.org/ecosystem), [community tooling page](https://internetcomputer.org/tooling), and the internetcomputer.org ['How it works'](https://internetcomputer.org/how-it-works) series.
 
 The ICP developer portal uses [Docusaurus](https://docusaurus.io/docs).
 
@@ -64,7 +64,7 @@ docs
 │   │   ├── http-compatible-canisters
 │   │   ├── user-login
 ├── motoko // Motoko documentation - submodule
-├── references // reference documentation
+├── specifications // reference documentation
 ├── samples // sample projects - submodule
 ├── tutorials // tutorial series (developer liftoff, hackathon prep course, etc).
 ```
@@ -158,11 +158,11 @@ A reference page provides low level detail into a feature or technology. API ref
 ### 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](https://internetcomputer.org/docs/current/references/bitcoin-how-it-works) pages
+- The [reference technology overview](https://internetcomputer.org/docs/references/bitcoin-how-it-works) pages
 
 - The [how it works](https://internetcomputer.org/how-it-works) section of the website
 
-- The [core concepts](https://internetcomputer.org/docs/current/concepts/canisters-code) section of the docs
+- The [core concepts](https://internetcomputer.org/docs/building-apps/essentials/canisters) section of the docs
 
 Try to answer the following questions within the document:
 
@@ -371,35 +371,35 @@ Failing to do so will break the code that auto-populates the Tooltip with the ap
 
 The developer docs utilize submodules for several subfolders of documentation. To edit these pages, changes must be made in the submodule's repo and merged into that repo. Then you must open a PR in this repo that pulls the latest submodule updates to apply the changes.
 
-The following submoules and their corresponding repos are currently used:
+The following submodules and their corresponding repos are currently used:
 
 - SDK
-    - `/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/`
+    - `/docs/building-apps/developer-tools/dfx/`
     - GitHub Repo: https://github.com/dfinity/sdk.git
 
 - Motoko
-    - `/docs/current/motoko/main/base/`
+    - `/docs/motoko/main/base/`
     - GitHub Repo: https://github.com/dfinity/motoko.git
 
 - quill
-    - `/docs/current/developer-docs/developer-tools/cli-tools/quill`
+    - `/docs/building-apps/developer-tools/quill`
     - GitHub Repo: https://github.com/dfinity/quill.git
 
 - Internet Identity
-    - `/docs/current/references/ii-spec`
+    - `/docs/references/ii-spec`
 	- GitHub Repo: https://github.com/dfinity/internet-identity.git
 
 - Sample projects
-    - `/docs/current/references/samples`
+    - `/docs/references/samples`
     - GitHub Repo: https://github.com/dfinity/examples.git
     - Note: This submodule intentionally uses `.md` files instead of `.mdx` files. Therefore, these pages do not support components such as tags and tooltips.
 
 - dfxvm
-    - `/docs/current/developer-docs/developer-tools/cli-tools/dfxvm/docs/cli-reference/dfx/`
+    - `/docs/building-apps/developer-tools/dfxvm/dfx/`
     - GitHub Repo: https://github.com/dfinity/dfxvm.git
 
 - Response verification
-    - `/docs/current/developer-docs/web-apps/http-compatible-canisters/custom-http-canisters`
+    - `/docs/building-apps/network-features/using-http/http-certification/`
     - GitHub Repo: https://github.com/dfinity/response-verification
 
 ### Updating submodules
@@ -538,14 +538,13 @@ The `.subpage.md` files will each generate a subpage under `/how-it-works/`, bas
 
 ## Adding documentation for community-created agents and CDKs
 
-The [agents](https://internetcomputer.org/docs/current/developer-docs/build/agents)
-and [CDKs](https://internetcomputer.org/docs/current/developer-docs/build/cdks) sections should not only contain docs
+The [agents](/docs/building-apps/interact-with-canisters/agents/overview)
+and [CDKs](/docs/building-apps/developer-tools/cdks/index) sections should not only contain docs
 for DFINITY-created agents and CDKs.
 We therefore invite other projects to:
 
 - Link to their own agents or CDKs on the respective index pages (the files to be edited are
-  in `docs/developer-docs/build/agents/index.md` or `docs/developer-docs/smart-contracts/write/overview.mdx`).
-- Add their own documentation as a folder under `Agents` or `CDKs`.
+  in `/docs/building-apps/interact-with-canisters/agents/overview` or `/docs/building-apps/developer-tools/cdks/index.md`).
 
 ## Adding community-created developer tools
 

blog/features/async-performance-counter.md

@@ -16,7 +16,7 @@ image: /img/blog/async-performance-counter.webp
 
 The Internet Computer can host a full dapp — frontend, backend and data. Users can deploy their dapp as a canister (smart contract) on the Internet Computer. Each canister can store up to 500GiB of data and execute up to 40 Billion WebAssembly instructions per transaction.
 
-Unlike other blockchains, the Internet Computer offers developers [enormous amounts of resources](/docs/current/developer-docs/smart-contracts/maintain/resource-limits). This poses a real challenge for canister developers: writing efficient canister code. The more efficient a canister is, the less cycles it pays.
+Unlike other blockchains, the Internet Computer offers developers [enormous amounts of resources](/docs/building-apps/canister-management/resource-limits). This poses a real challenge for canister developers: writing efficient canister code. The more efficient a canister is, the less cycles it pays.
 
 Performance counter is the way for a canister (smart contract) to track the amount of work done. This information could be used as the main metric to optimize the code.
 
@@ -113,7 +113,7 @@ But in this case there is no need to instrument every single await point in the
 
 ## Using performance counters
 
-To quickly run the performance counters example (assuming the Internet Computer SDK is [already installed](/docs/current/developer-docs/getting-started/install)):
+To quickly run the performance counters example (assuming the Internet Computer SDK is [already installed](/docs/building-apps/getting-started/install)):
 
 ```
 $ git clone [email protected]:dfinity/examples.git
@@ -143,6 +143,6 @@ Python:     from kybra import ic
 
 ## References
 
-- Backend developers guide: [Optimizing Rust canisters](/docs/current/developer-docs/backend/rust/optimizing).
+- Backend developers guide: [Optimizing Rust canisters](/docs/building-apps/advanced/optimize/rust).
 
-- Motoko developers guide: [Optimizing canisters](/docs/current/motoko/main/getting-started/motoko-introduction).
+- Motoko developers guide: [Optimizing canisters](/docs/motoko/main/getting-started/motoko-introduction).

blog/features/composite-query.md

@@ -73,7 +73,7 @@ The complete code can be found [here](https://github.com/dfinity/examples/tree/m
 An alternative implementation for Motoko can be found [here](https://github.com/dfinity/examples/tree/master/motoko/composite_query).
 
 ## Using composite queries
-To start, let's set up our development environment. Make sure you have [dfx](/docs/current/developer-docs/getting-started/install) installed on your computer. You will need at least version 0.15.0 of dfx for composite query support. Open your terminal and follow these commands:
+To start, let's set up our development environment. Make sure you have [dfx](/docs/building-apps/getting-started/install) installed on your computer. You will need at least version 0.15.0 of dfx for composite query support. Open your terminal and follow these commands:
 
 ```bash
 DFX_VERSION=0.15.0-beta.1 sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)"

blog/features/deprecating-the-service-worker.md

@@ -10,7 +10,7 @@ image: /img/blog/deprecating-the-service-worker.png
 
 ## Introduction
 
-The DFINITY Foundation would like to propose deprecating the Internet Computer Service Worker in favor of ICX Proxy on the DFINITY hosted [Boundary Nodes](https://wiki.internetcomputer.org/wiki/Boundary_Nodes). We believe that this change will have dramatic improvements to end user and developer experience while reducing complexity in the Internet Computer’s [HTTP Gateway Protocol](/docs/current/references/ic-interface-spec#http-gateway), without reducing security or changing trust assumptions.
+The DFINITY Foundation would like to propose deprecating the Internet Computer Service Worker in favor of ICX Proxy on the DFINITY hosted [Boundary Nodes](https://wiki.internetcomputer.org/wiki/Boundary_Nodes). We believe that this change will have dramatic improvements to end user and developer experience while reducing complexity in the Internet Computer’s [HTTP Gateway Protocol](/docs/references/ic-interface-spec#http-gateway), without reducing security or changing trust assumptions.
 
 Keep reading to learn more about why we believe this is the right path forward and the roadmap that we are suggesting for this transition.
 
@@ -32,7 +32,7 @@ Presently, there are three distinct implementations of this protocol: the Servic
 
 ### The Service Worker
 
-The Service Worker operates on `{canisterId}.ic0.app` and `{canisterId}.icp0.io` URLs as well as [Boundary Node hosted custom domains](/docs/current/developer-docs/web-apps/custom-domains/using-custom-domains). For example, Internet Identity can be accessed via the Service Worker using the following URLs:
+The Service Worker operates on `{canisterId}.ic0.app` and `{canisterId}.icp0.io` URLs as well as [Boundary Node hosted custom domains](/docs/building-apps/frontends/custom-domains/using-custom-domains). For example, Internet Identity can be accessed via the Service Worker using the following URLs:
 
 - [rdmx6-jaaaa-aaaaa-aaadq-cai.ic0.app](https://rdmx6-jaaaa-aaaaa-aaadq-cai.ic0.app/)
 - [rdmx6-jaaaa-aaaaa-aaadq-cai.icp0.io](https://rdmx6-jaaaa-aaaaa-aaadq-cai.icp0.io/)
@@ -188,7 +188,7 @@ The goal of the short term roadmap is to make a relatively quick transition to I
 
 **Timeline:** From present day up to 2-3 weeks.
 
-This is the current phase that we are in now. We are currently working on gathering metrics for the size of [streamed response bodies](/docs/current/references/http-gateway-protocol-spec#response-body-streaming). This is important because these responses are currently not verified by ICX Proxy. We would suggest gathering these metrics for the next couple of weeks in order to make an educated decision about the next step of the transition.
+This is the current phase that we are in now. We are currently working on gathering metrics for the size of [streamed response bodies](/docs/references/http-gateway-protocol-spec#response-body-streaming). This is important because these responses are currently not verified by ICX Proxy. We would suggest gathering these metrics for the next couple of weeks in order to make an educated decision about the next step of the transition.
 
 #### Limited certified response body streaming
 

blog/features/dfx-deps.md

@@ -122,7 +122,7 @@ After this step, the pulled dependencies can be deployed on a local replica usin
 
 ## Conclusion
 
-The `dfx deps` feature is available in dfx versions `0.14.1` and newer. You can learn more from our [developer documentation](/docs/current/developer-docs/smart-contracts/maintain/import), which includes an interactive example you can use to test the feature for yourself.
+The `dfx deps` feature is available in dfx versions `0.14.1` and newer. You can learn more from our [developer documentation](/docs/building-apps/advanced/using-third-party-canisters), which includes an interactive example you can use to test the feature for yourself.
 
 As always, please let us know if you have any feedback either through our [forum](https://forum.dfinity.org/) or [Discord server](https://discord.com/invite/5PJMmmETQB).
 

blog/features/evm-rpc-canister-launch.mdx

@@ -40,7 +40,7 @@ or submitting feedback on the
 
   <a
     className={"button button-primary"}
-    href={"https://internetcomputer.org/docs/current/developer-docs/multi-chain/ethereum/evm-rpc/evm-rpc-canister"}
+    href={"https://internetcomputer.org/docs/building-apps/chain-fusion/ethereum/evm-rpc/evm-rpc-canister"}
   >
     View the documentation
   </a>
@@ -116,7 +116,7 @@ hopefully it still shows you how easy it is to get started.
 
 <!-- prettier-ignore-start -->
 :::info
-Please ensure you [install](/docs/current/developer-docs/getting-started/install) `dfx` before proceeding with the steps below.
+Please ensure you [install](/docs/building-apps/getting-started/install) `dfx` before proceeding with the steps below.
 :::
 <!-- prettier-ignore-end -->
 

blog/features/improving-query-latencies.md

@@ -111,5 +111,5 @@ The new functionality is transparent and available on all the subnets and local
 
 - [Source code of the Internet Computer query cache implementation](https://github.com/dfinity/ic/)
 
-- [The Internet Computer interface specification: Synchronicity across nodes](/docs/current/references/ic-interface-spec#synchronicity-across-nodes)
+- [The Internet Computer interface specification: Synchronicity across nodes](/docs/references/ic-interface-spec#synchronicity-across-nodes)
 

blog/features/motoko-dev-server.md

@@ -25,7 +25,7 @@ However, this feature is almost nonexistent when developing a decentralized appl
 
 ---
 
-This is where the [Motoko programming language](/docs/current/motoko/main/getting-started/motoko-introduction) comes in. With quick compilation times, module-based imports, and [stable variable](/docs/current/motoko/main/canister-maintenance/upgrades) semantics, Motoko is the ideal candidate for a game-changing live reload workflow.
+This is where the [Motoko programming language](/docs/motoko/main/getting-started/motoko-introduction) comes in. With quick compilation times, module-based imports, and [stable variable](/docs/motoko/main/canister-maintenance/upgrades) semantics, Motoko is the ideal candidate for a game-changing live reload workflow.
 
 Over the past six months, DFINITY has adopted full-stack live reloading in our internal Motoko projects, saving a huge amount of development time and allowing us to quickly try lots of different ideas to improve the end-user experience of our Internet Computer dapps.
 
@@ -63,13 +63,13 @@ Once you’ve installed the tool, run `mo-dev --help` to view usage examples and
 
 ## Candid UI
 
-Let’s say you’re developing a Motoko smart contract using the [Candid UI](/docs/current/developer-docs/smart-contracts/candid/candid-concepts). Here’s a command which will redeploy the canister on file change:
+Let’s say you’re developing a Motoko smart contract using the [Candid UI](/docs/building-apps/interact-with-canisters/candid/candid-concepts). Here’s a command which will redeploy the canister on file change:
 
 ```sh
 mo-dev --deploy -y
 ```
 
-The `-y` flag automatically responds “yes” to prompts from [dfx](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-deploy) about upgrading the canister interface (potentially clearing canister data). Feel free to include or omit this depending on your use case.
+The `-y` flag automatically responds “yes” to prompts from [dfx](/docs/building-apps/developer-tools/dfx/dfx-deploy) about upgrading the canister interface (potentially clearing canister data). Feel free to include or omit this depending on your use case.
 
 ## Full-Stack Dapp
 
@@ -100,7 +100,7 @@ With this project configuration, `npm start` will run the Vite and Motoko dev se
 
 Another benefit of this configuration is that anyone can run the dev server without needing to globally install the `mo-dev` command, which is great for encouraging open-source contributions or working as part of a team.
 
-This project configuration will be included by default in the upcoming changes to the [dfx new](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-new) command.
+This project configuration will be included by default in the upcoming changes to the [dfx new](/docs/building-apps/developer-tools/dfx/dfx-new) command.
 
 `mo-dev` ships with a test runner compatible with third-party libraries such as motoko-matchers.
 
@@ -163,7 +163,7 @@ CI=true mo-dev --generate --deploy
 Here are a few miscellaneous tips which might come in handy while working with `mo-dev`:
 
 * Live reloading works when switching Git branches, which is useful to keep in mind for code reviews and pair programming.
-* If you’ve used [dfx generate](/docs/current/developer-docs/developer-tools/cli-tools/cli-reference/dfx-generate), you might have encountered a common catch-22 where both `dfx generate` and `dfx deploy` require running each other first. `mo-dev --generate --deploy` automatically handles this situation for you.
+* If you’ve used [dfx generate](/docs/building-apps/developer-tools/dfx/dfx-generate), you might have encountered a common catch-22 where both `dfx generate` and `dfx deploy` require running each other first. `mo-dev --generate --deploy` automatically handles this situation for you.
 * You can define custom live-reload logic using `mo-dev --exec <command>`.
 
 ---