aws-cqc / aws-cqc/DeviceLayout.jl

Documentation improvements

Open
#25 0 comments 0 reactions 0 assignees View on GitHub
documentation help wanted
Dominant language
Julia
Stars
67
Forks
14
Avg merge
1d 16h
Merged PRs (30d)
21

Description

It would be greatly appreciated if anyone wants to go over the documentation with fresh eyes (that's mainly why I added a "help wanted" label here), but a few things jump out even at me:

- ~The quick start example on the home page doesn't really showcase capabilities besides the most basic `Cell` workflow. I do think that's good for getting started quickly, but even as far as geometry-level layout we want to encourage users to place things in `CoordinateSystem`s and render to `Cell` at the end. Keep in mind that this might be the user's first encounter with DeviceLayout.jl.~ Done -- the "hello world" example still uses Cell, but the First Layout tutorial introduces CoordinateSystems.
- ~We should at least include the list of features from the README and link to the examples with pretty pictures.~ [Done.](https://github.com/aws-cqc/DeviceLayout.jl/commit/0ae0d4e16010a6241cb216d9665ca391a7710806)
- Should note somewhere that these are general 2D/2.5D device CAD capabilities—we are focusing on the quantum use case right now since that's what we can most readily make examples and do support/outreach for
- ~Several pages mix narrative explanation and how-tos with interspersed `@docs` block references. It might be better to separate these (consider [the four-document model](https://diataxis.fr/)).~ Done.
- ~Several pages have little or no explanation, just the reference.~ Reference and explanation are split.
- ~Troubleshooting/FAQ pages for geometry and schematic layout should be consolidated (can still use separate sections on one page)—users shouldn't have to think about whether to check one or the other.~ Done.
- Could use more how-tos and examples in general
- There are likely many minor issues like `center(::Schematic, ::ComponentNode)` appearing [under `center` on the geometry page](https://aws-cqc.github.io/DeviceLayout.jl/dev/geometry/#DeviceLayout.center) (rather than only on the page about schematics), or `center(::Polygon)` having its own docstring despite being the same as the generic `center`. (Those in particular are fixed by https://github.com/aws-cqc/DeviceLayout.jl/pull/58.)

See also #1, #2, #3, #14. I'm collecting these notes in one issue to help sort out the structural goals for major revisions, but we can break this down into multiple sub-issues/PRs.

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the README, home page, First Layout tutorial, geometry and schematics pages, and the troubleshooting/FAQ material. Identify which documentation gaps remain after the items marked done and PR #58, then split the remaining work into focused changes. Done means the documentation clearly explains the general 2D/2.5D CAD scope and provides additional how-tos or examples without misplaced or redundant references.

Written by the indexing model from the issue text.

Assessment

Tech stack
julia
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.