https://pantsbuild.org/ logo
#development
Title
# development
w

witty-crayon-22786

09/23/2022, 4:23 PM
another docs open question: we got feedback that it isn’t always obvious that tabbed code blocks might represent a complete working example:
i’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 PM
It 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.. ?
Or create a gist/repo and link to that is ready to clone and run..
w

witty-crayon-22786

09/23/2022, 4:27 PM
yea, 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 PM
Or 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 PM
folks might expect that the tabs represent different versions
yea I’ve seen those… but then they’ve not really read the tab titles, surely.
Perhaps 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 PM
I 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 PM
I’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 PM
for 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 PM
Plugin API docs.
👍 1
If 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