Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

feat: reorganizing docs to fit diataxis framework #3711

Merged
merged 7 commits into from
Dec 11, 2023
Merged

feat: reorganizing docs to fit diataxis framework #3711

merged 7 commits into from
Dec 11, 2023

Conversation

signorecello
Copy link
Contributor

@signorecello signorecello commented Dec 7, 2023 •
edited
Loading

Description

One of DevRel goals was to slowly start designing our docs process, and specially adopting the Diátaxis framework. A quick picture should make it easy to understand what exactly is Diátaxias:

diataxis

Relevant WIP docs for this are (internal links):

This PR is a first step towards that reorg, by essentially moving things around. There are little changes to the content itself for now.

However, during the reorg process, an opportunity came to upgrade to Docusaurus v3.0 with very little overhead, so I took it.

Problem*

A small retro was made as part of the above Noir Docs 2.0 exercise.

Summary*

The Diátaxis framework divides docs neatly into four sections. However, in this case, it was deemed important to give a quick reference, so as to tackle the initial interest and motivation of readers and tinkerers.

So, five top-level sections:

  • Getting Started -> Has a quick reference for all of the other sections, by providing a guide, a tutorial, an explanation, and a small reference to other tools. The idea is that most user journeys will eventually start here.
  • "The Noir Language" -> One of the biggest tasks will be to neatly separate explanations from reference material. This is a task that will be done later on. So this section contains a hybrid.
  • How-To Guides -> Given the clear distinction between "How-To" and "Tutorial", which is important to keep, this section currently doesn't have any more than the potentially outdated Merkle Tree example.
  • Tutorials -> Again, since no content was added, only the NoirJS e2e example is in this section.
  • Reference -> The reference material for Nargo commands and NoirJS lives here. This will be gradually expanded to fit the reference in the Language section.

@github-actions github-actions bot added the documentation Improvements or additions to documentation label Dec 7, 2023
@socket-security Socket Security
Copy link

socket-security bot commented Dec 7, 2023 •
edited
Loading

New, updated, and removed dependencies detected. Learn more about Socket for GitHub ↗︎

Packages Version New capabilities Transitives Size Publisher
@docusaurus/tsconfig 3.0.1 None +0 2.13 kB slorber
@docusaurus/core 3.0.1 environment +205 16.7 MB slorber
@docusaurus/module-type-aliases 3.0.1 None +4 4.96 MB slorber
@docusaurus/types 3.0.1 None +3 4.94 MB slorber
react 18.2.0 None +0 316 kB gnoff
react-dom 18.2.0 None +2 4.91 MB gnoff
prism-react-renderer 2.3.0 None +4 767 kB formidablelabs
typescript 5.2.2 None +0 40.6 MB typescript-bot
@docusaurus/preset-classic 2.4.3...3.0.1 None +454/-54 39.8 MB slorber
rehype-katex 5.0.0...7.0.0 None +52/-10 9.25 MB wooorm
remark-math 3.0.1...6.0.0 None +100/-0 11.3 MB wooorm
@mdx-js/react 1.6.22...3.0.0 None +2/-0 33.2 kB wooorm
prettier 3.1.0...3.1.1 None +0/-0 8.42 MB prettier-bot

🚮 Removed packages: @docusaurus/plugin-google-gtag@2.4.3

@github-actions GitHub Actions
Copy link
Contributor

github-actions bot commented Dec 7, 2023 •
edited
Loading

🚀 Deployed on https://6577699032cd9e3af2d2b43a--noir-docs.netlify.app

TomAFrench
TomAFrench reviewed Dec 11, 2023
View reviewed changes
docs/.eslintrc.js Outdated Show resolved Hide resolved
TomAFrench
TomAFrench reviewed Dec 11, 2023
View reviewed changes
docs/.prettierrc Outdated Show resolved Hide resolved
@Savio-Sou
Copy link
Collaborator

How-To Guides -> Given the clear distinction between "How-To" and "Tutorial", which is important to keep, this section currently doesn't have any more than the potentially outdated Merkle Tree example.

Thanks for the references linked. What’s the difference between a tutorial and how-to guide? is an interesting read.

Curious how do you vision https://github.com/noir-lang/noir-examples/ to be, and if applicable, how best to repurpose #3551?

@signorecello signorecello added this pull request to the merge queue Dec 11, 2023
@signorecello
Copy link
Contributor Author

Well as fellow devrel at heart, it's only natural we share the love for documentation!

My vision for noir-examples is a repository with a collection of examples for common things like ECDSA signature verification, merkle tree membership, recursion, etc, if possible grouped together in big, deployable, ready-to-clone examples. A perfect example is stealthdrop, which combines multiple language concepts into one big project.

It is not meant to be up-to-date, unless breaking changes show up. By trusting the community to flag when some change goes undetected by devrel (which inevitably happens), we can keep them fairly up-to-date with the latest syntax without depleting all of our time.

In the future though, we could have a CI that auto-builds the examples with latest nargo and flags if they require maintenance. This could be interesting

Merged via the queue into master with commit 54a1ed5 Dec 11, 2023
33 checks passed
@signorecello signorecello deleted the zpedro/docs_reorg branch December 11, 2023 23:53
@kevaundray kevaundray mentioned this pull request Dec 11, 2023
Closed
@signorecello signorecello mentioned this pull request Dec 12, 2023
Merged
@kevaundray kevaundray mentioned this pull request Dec 15, 2023
Merged
kevaundray added a commit that referenced this pull request Dec 15, 2023
@kevaundray
chore: Release Noir(0.21.0) (#3824)
e7fb36b 
🤖 I have created a release *beep* *boop*
---


<details><summary>0.21.0</summary>

## [0.21.0](v0.20.0...v0.21.0)
(2023-12-15)


### ⚠ BREAKING CHANGES

* remove unused `source-resolver` package
([#3791](#3791))
* Make file manager read-only to the compiler
([#3760](#3760))

### Features

* Add `prelude.nr`
([#3693](#3693))
([5f0f81f](5f0f81f))
* Add some traits to the stdlib
([#3796](#3796))
([8e11352](8e11352))
* Add support for writing tracing debug info to file
([#3790](#3790))
([98a5004](98a5004))
* Allow passing custom foreign call handlers when creating proofs in
NoirJS ([#3764](#3764))
([6076e08](6076e08))
* Allow underscores in integer literals
([#3746](#3746))
([2c06a64](2c06a64))
* Avoid overflow checks on boolean multiplication
([#3745](#3745))
([9b5b686](9b5b686))
* Aztec-packages
([#3754](#3754))
([c043265](c043265))
* Dockerfile to test cargo and JS packages
([#3684](#3684))
([513d619](513d619))
* Docs landing page with a playground
([#3667](#3667))
([9a95fbe](9a95fbe))
* Enhance test information output
([#3696](#3696))
([468fbbc](468fbbc))
* Implement print without newline
([#3650](#3650))
([9827dfe](9827dfe))
* **lsp:** Add goto definition for locals
([#3705](#3705))
([9dd465c](9dd465c))
* **lsp:** Add goto definition for structs
([#3718](#3718))
([a576c5b](a576c5b))
* Optimize out unnecessary truncation instructions
([#3717](#3717))
([c9c72ae](c9c72ae))
* Remove experimental feature warning for traits
([#3783](#3783))
([cb52242](cb52242))
* Reorganizing docs to fit diataxis framework
([#3711](#3711))
([54a1ed5](54a1ed5))
* Simplify explicit equality assertions to assert equality directly
([#3708](#3708))
([2fc46e2](2fc46e2))
* Speed up transformation of debug messages
([#3815](#3815))
([2a8af1e](2a8af1e))


### Bug Fixes

* `try_unify` no longer binds types on failure
([#3697](#3697))
([f03e581](f03e581))
* Add missing assertion to test
([#3765](#3765))
([bcbe116](bcbe116))
* Add negative integer literals
([#3690](#3690))
([8b3a68f](8b3a68f))
* Allow trait method references from the trait name
([#3774](#3774))
([cfa34d4](cfa34d4))
* Deserialize odd length hex literals
([#3747](#3747))
([4000fb2](4000fb2))
* **docs:** Trigger `update-docs` workflow when the `release-please` PR
gets merged and not on every merge to master
([#3677](#3677))
([9a3d1d2](9a3d1d2))
* Initialise strings as u8 array
([#3682](#3682))
([8da40b7](8da40b7))
* **lsp:** Package resolution on save
([#3794](#3794))
([14f2fff](14f2fff))
* Parse negative integer literals
([#3698](#3698))
([463ab06](463ab06))
* Pub is required on return for entry points
([#3616](#3616))
([7f1d796](7f1d796))
* Remove `noirc_driver/aztec` feature flag in docker
([#3784](#3784))
([a48d562](a48d562))
* Remove include-keys option
([#3692](#3692))
([95d7ce2](95d7ce2))
* Revert chnage to modify version in workspace file for acvm
dependencies ([#3673](#3673))
([0696f75](0696f75))
* Sequence update-lockfile workflow so it gets modified after the ACVM
version in the root has been changed
([#3676](#3676))
([c00cd85](c00cd85))
* **ssa:** Handle array arguments to side effectual constrain statements
([#3740](#3740))
([028d65e](028d65e))
* Stop cloning Traits!
([#3736](#3736))
([fcff412](fcff412))
* Stop issuing unused variable warnings for variables in trait
definitions ([#3797](#3797))
([0bb44c3](0bb44c3))
* Unsigned integers cannot be negated
([#3688](#3688))
([f904ae1](f904ae1))


### Miscellaneous Chores

* Make file manager read-only to the compiler
([#3760](#3760))
([e3dcc21](e3dcc21))
* Remove unused `source-resolver` package
([#3791](#3791))
([57d2505](57d2505))
</details>

<details><summary>0.37.1</summary>

## [0.37.1](v0.37.0...v0.37.1)
(2023-12-15)


### Features

* Aztec-packages
([#3754](#3754))
([c043265](c043265))
* Speed up transformation of debug messages
([#3815](#3815))
([2a8af1e](2a8af1e))


### Bug Fixes

* Deserialize odd length hex literals
([#3747](#3747))
([4000fb2](4000fb2))
</details>

---
This PR was generated with [Release
Please](https://github.com/googleapis/release-please). See
[documentation](https://github.com/googleapis/release-please#release-please).
@Savio-Sou Savio-Sou mentioned this pull request Jan 16, 2024
Closed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@TomAFrench TomAFrench TomAFrench left review comments

@Savio-Sou Savio-Sou Savio-Sou approved these changes

@kevaundray kevaundray Awaiting requested review from kevaundray

Assignees
No one assigned
Labels
documentation Improvements or additions to documentation
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.

None yet
3 participants
@signorecello @Savio-Sou @TomAFrench