I'm getting an increasing number of questions and inquiries, many of which are answered by the documentation in the various dialect rationales. In general, i think we have extremely lackluster documentation wrt. "getting started" in CIRCT. We describe how to build the project which seems to be duplicated somewhere else.
If people do figure out that what they're looking for is dialect-specific documentation, they're greeted with the Dialects doc site which points to the autogenerated documentation... where, in practice, users probably should be routed to dialect rationales before getting thrown into esoteric autogenerated op documentation.
But how do people even know that there's a dialect rationale to begin with? it's buried beneath a subtle + menu which then finally leads you to the entry point for a dialect...
And after that, our general best suggestion to get started in CIRCT is to read tests. Which I in principle agree with, but we have no introduction about what we actually mean when we say "read the tests" - that is, information conveying "this is a LIT test", "this is a pass pipeline", "you're expected to bring IR at some level, and the point of CIRCT is to provide passes to transform through various abstractions", and so forth...
mortbopet
commented
1 year ago
A more elaborated/continued rant of https://github.com/llvm/circt/issues/5545
I'm getting an increasing number of questions and inquiries, many of which are answered by the documentation in the various dialect rationales. In general, i think we have extremely lackluster documentation wrt. "getting started" in CIRCT. We describe how to build the project which seems to be duplicated somewhere else.
If people do figure out that what they're looking for is dialect-specific documentation, they're greeted with the Dialects doc site which points to the autogenerated documentation... where, in practice, users probably should be routed to dialect rationales before getting thrown into esoteric autogenerated op documentation.
But how do people even know that there's a dialect rationale to begin with? it's buried beneath a subtle
+menu which then finally leads you to the entry point for a dialect...And after that, our general best suggestion to get started in CIRCT is to read tests. Which I in principle agree with, but we have no introduction about what we actually mean when we say "read the tests" - that is, information conveying "this is a LIT test", "this is a pass pipeline", "you're expected to bring IR at some level, and the point of CIRCT is to provide passes to transform through various abstractions", and so forth...