Skip to content

Commit

Permalink
feat: Restructure the documentation (#278)
Browse files Browse the repository at this point in the history
PR is in draft state: Some links are broken, highlight of active section
in header is broken, redirects from old pages to new ones are not added.

The content, however, is *in place and fully reviewable*.

---

This PR restructures the ZKsync Era documentation.

> [!WARNING]  
>No nitpick territory! Restructuring is highly subjective, and
bikeshedding about big restructuring may introduce delays in getting
this PR merged. Let's focus on critical issues here, and fix everything
else in follow-up PRs.

## New structure

I will not describe what moved where exactly. Instead, I invite
reviewers to check the preview and try to find the information they care
about. If it's hard to do and the place is not intuitive -- probably the
restructuring doesn't work as intended.

However, here're some highlights:
- Documentation is majorly restructured into three sections:
- ZKsync Era: Everything about building _on_ Era (or any other chain).
Highly practical, focused on dApp developers.
- ZK Stack: Everything about running your own stack. Again, focused on
actions rather than on theory.
	- ZKsync Protocol: Theoretical information about the protocol.
- SDK docs were embedded into the documentation instead of hosting them
as another top-level category.

## New content

I've tried to minimize the amount of new content, but in some places I
felt that the sections are too incomplete (mostly in ZK Stack section).
I've added a few new pages with _minimum_ new information, just so that
we close the gaps in the narrative. These are to be extended later.

Content added:
- Changed the description of the sequencer in ZK Stack and added a link
to the core book.
- Changed the description of the prover in ZK Stack and added a link to
the prover book.
- Added a page about node framework.
## Removed pages

Some of the pages have been removed. It mostly includes pages that
either provide no information, pages that were copy-pasted from other
pages, and pages that are not relevant for ZKsync (e.g. information
available elsewhere).
Removed pages:
- [Elliptic Curve
Precompiles](https://docs.zksync.io/build/developer-reference/era-contracts/elliptic-curve-precompiles)
-- this is an overview of precompiles that are not yet available on
ZKsync.
- [L2->L1 Communication Before
Boojum](https://docs.zksync.io/build/developer-reference/handling-pubdata-in-boojum/l2-l1-communication-before-boojum)
-- no longer relevant
- [Migrating ZKsync Era into the ZK
chain](https://docs.zksync.io/build/developer-reference/migrate-era-to-chain)
-- no longer relevant
- [Batches and L2 Blocks on
ZKsync](https://docs.zksync.io/build/developer-reference/batches-and-l2-blocks)
-- mostly focuses on virtual blocks, no longer relevant, covered by
[Blocks and Batches](https://docs.zksync.io/zk-stack/concepts/blocks)
- [L1-L2
interoperability](https://docs.zksync.io/build/developer-reference/l1-l2-interoperability)
-- no substance, covered by [L1 <-> L2
communication](https://docs.zksync.io/zk-stack/concepts/l1_l2_communication)
- [FAQ](https://docs.zksync.io/build/resources/faq) -- I doubt that many
of those questions are actually frequently asked. This section is
useful, but we need to rework it to be more up-to-date and well
structured.
- [Community
channels](https://docs.zksync.io/build/resources/community-channels) --
This information is available on the [main
page](https://docs.zksync.io/)
- Most of the [Node](https://docs.zksync.io/zksync-node) section --
instead I provide the link to the much more up-to-date section of the
[core
book](https://matter-labs.github.io/zksync-era/core/latest/guides/external-node/01_intro.html).
  • Loading branch information
popzxc authored Dec 6, 2024
1 parent 545e021 commit 0ee9721
Show file tree
Hide file tree
Showing 525 changed files with 40,519 additions and 5,206 deletions.
5 changes: 4 additions & 1 deletion app.vue
Original file line number Diff line number Diff line change
@@ -1,4 +1,6 @@
<script setup lang="ts">
import { headerLinks } from './header-links';
const { seo } = useAppConfig();
const { data: navigation } = await useAsyncData('navigation', () => fetchContentNavigation());
Expand Down Expand Up @@ -43,7 +45,8 @@ useSeoMeta({
<NuxtPwaManifest />
<NuxtLoadingIndicator />

<HeaderComponent />
<!-- FIXME: Hack, we want to pass computed property while `useHeaderNav` expects an array -->
<HeaderComponent :links="computed(() => headerLinks()) as any" />

<UMain>
<NuxtLayout>
Expand Down
1 change: 0 additions & 1 deletion content/00.build/05.start-coding/_dir.yml

This file was deleted.

12 changes: 0 additions & 12 deletions content/00.build/20.zksync-cli/90.reference/00.index.md

This file was deleted.

36 changes: 0 additions & 36 deletions content/00.build/40.tooling/20.hardhat/00.index.md

This file was deleted.

1 change: 0 additions & 1 deletion content/00.build/40.tooling/20.hardhat/_dir.yml

This file was deleted.

1 change: 0 additions & 1 deletion content/00.build/40.tooling/30.foundry/_dir.yml

This file was deleted.

1 change: 0 additions & 1 deletion content/00.build/60.test-and-debug/_dir.yml

This file was deleted.

59 changes: 0 additions & 59 deletions content/00.build/65.developer-reference/00.index.md

This file was deleted.

50 changes: 0 additions & 50 deletions content/00.build/65.developer-reference/15.migrate-era-to-chain.md

This file was deleted.

Loading

0 comments on commit 0ee9721

Please sign in to comment.