aws-cqc / aws-cqc/DeviceLayout.jl
Documentation improvements
- 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
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