another docs open question: we got feedback that i...
# developmentw
witty-crayon-22786
09/23/2022, 4:23 PManother docs open question: we got feedback that it isn’t always obvious that tabbed code blocks might represent a complete working example:
witty-crayon-22786
09/23/2022, 4:24 PMi’m really not sure what to do about that… adding titles? trying to explain more of what to expect in the code block?
b
bitter-ability-32190
09/23/2022, 4:26 PMIt makes sense to me, but curse-of-knowledge and all that 😕
c
curved-television-6568
09/23/2022, 4:26 PM“This working example …” maybe.. ?
curved-television-6568
09/23/2022, 4:27 PMOr create a gist/repo and link to that is ready to clone and run..
w
witty-crayon-22786
09/23/2022, 4:27 PMyea, possibly… i think that folks might expect that the tabs represent different versions of the same file (they are often used to demonstrate the same API in multiple languages)
b
bitter-ability-32190
09/23/2022, 4:27 PMOr create a gist/repo and link to that is ready to clone and run..That'd be badass. Especially if it was automated (text synced from the gist/repo)
🤪 1
c
curved-television-6568
09/23/2022, 4:28 PMfolks might expect that the tabs represent different versionsyea I’ve seen those… but then they’ve not really read the tab titles, surely.
curved-television-6568
09/23/2022, 4:30 PMPerhaps better to stack them all files on a single pane, with only comments indicating which file they belong to in order to show the full example in a single view, but then the syntax highlighting would be off.. oh, unless using multiple blocks, only don’t tab them..
➕ 1
🤔 1
h
hundreds-father-404
09/23/2022, 4:32 PMI suspect something like this is sufficient:
For example (see each tab):I don't like the Gist idea because we lose the benefit of in-repo docs, that we can grep for broken code examplse when we make changes
a
ambitious-actor-36781
09/26/2022, 8:58 PMI’ve found some examples are “incomplete” in the sense I have to go dig for which import it uses.
➕ 1
h
hundreds-father-404
09/26/2022, 9:08 PMfor Plugin API stuff @ambitious-actor-36781? Or for User stuff? (b/c you should need imports for user stuff)
a
ambitious-actor-36781
09/26/2022, 9:20 PMPlugin API docs.
👍 1
ambitious-actor-36781
09/26/2022, 9:24 PMIf there was a complete, runnable example at some point on the page, that would be ideal.
The incremental code blocks help with context building, but it’s hard to see the big picture
➕ 1
👍 1