feat: docs for batch spec library and templates#1244
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
Hi @bahrmichael thanks for the updates. Are these related to 6.6 release? |
Yes! Do you want to take over the PR and point it to a release branch? |
Cool, yes I can take over. Just for everyone else's visibility can you also please open a GTM ticket: https://linear.app/sourcegraph/issue-label/gtm%20enablement |
aulorbe
left a comment
aulorbe
left a comment
There was a problem hiding this comment.
Overall I think this is looking really good! I'm super excited about this feature. I think we can improve clarity a little bit throughout just by using more succinct and specific language. LMK if you have any Qs about my feedback!
| ## Batch Spec Library | ||
|
|
||
| <Callout type="note"> Batch Spec Library is currently in Experimental.</Callout> | ||
| The Batch Spec Library accelerates batch change adoption by offering curated examples and guided templates that make large-scale code modifications accessible to developers at every skill level. |
There was a problem hiding this comment.
To me, this sounds like it should be internal because of the word "adoption" -- like, it seems like we're saying leaving a note for our marketing team that the Library aims to increase BC adoptions b/c XYZ. Maybe rephrase to something like "The Batch Spec Library offers curated examples..." ?
There was a problem hiding this comment.
This page is for the site-admin, so I was comfortable with telling them "use this feature to make it easier for folks who use the product you operate". I'll replace the acceleration part.
| The Batch Spec Library accelerates batch change adoption by offering curated examples and guided templates that make large-scale code modifications accessible to developers at every skill level. | ||
|
|
||
| The Batch Spec Library is a collection of Batch Specs that can be used to create Batch Changes. Sourcegraph provides a few Batch Specs out of the box. | ||
| The library distinguishes between [templates](#templates) and [library examples](#library-examples), where library examples are complete batch specs and templates are library examples with variables. |
There was a problem hiding this comment.
I'd just say "examples" (not "library examples") here, since you say library @ the start of the sentence.
There was a problem hiding this comment.
This sentence strikes me as a little bit confusing:
where library examples are complete batch specs and templates are library examples > with variables.
Maybe we could rephrase to something like "[new sentence] Examples are batch specs (link to specs documentation) that are meant to be modified by power users who are comfortable writing code; Templates, on the other hand, are batch specs that contain variables that the user can inject data dynamically into (e.g. a form), and are meant to be used by general users."
There was a problem hiding this comment.
I like your suggestion!
| The Batch Spec Library is a collection of Batch Specs that can be used to create Batch Changes. Sourcegraph provides a few Batch Specs out of the box. | ||
| The library distinguishes between [templates](#templates) and [library examples](#library-examples), where library examples are complete batch specs and templates are library examples with variables. | ||
|
|
||
| Sourcegraph instances come with a couple of library examples out of the box. You can use the GraphQL APIs to [manage the Batch Spec Library](#managing-the-batch-spec-library). |
There was a problem hiding this comment.
I'd say "Examples" and "Templates" (capitalized) instead of "library examples" and "templates" throughout
There was a problem hiding this comment.
I'm not sure about capitalizing the words, and can't really explain why. I'll push an update so we can see how it reads.
|
|
||
| Sourcegraph instances come with a couple of library examples out of the box. You can use the GraphQL APIs to [manage the Batch Spec Library](#managing-the-batch-spec-library). | ||
|
|
||
| As a site admin, you can [feature records](#featured-records) to highlight the most useful examples for your organization. |
There was a problem hiding this comment.
Can you do this w/templates too?
And if you like a template, can you turn it into a canonical example when the variables are filled out?
There was a problem hiding this comment.
Yes you can! I've updated the wording to mention both templates and examples
And if you like a template, can you turn it into a canonical example when the variables are filled out?
You can do that, but need to create it under a different name. I haven't thought about customers turning templates into examples though.
There was a problem hiding this comment.
Yeah! I mean, this is tangential to this PR of course, but I think that'd be awesome! Like, look, I created a dope batch spec, lemme put that into the canonical lib of examples for my org (given some review)
|
|
||
| ### Library examples | ||
|
|
||
| Library examples are complete batch specs intended for advanced users who are comfortable working with YAML and writing code. These examples serve as inspiration and starting points for custom batch changes, providing reference implementations that can be adapted to specific use cases. |
There was a problem hiding this comment.
"reference implementations" is a bit abstract here -- what does this mean exactly? Aren't Examples themselves "reference implementations"?
There was a problem hiding this comment.
Hm, I think that part of the sentence doesn't add any value. It's the same as the first half, but more generic words :D
|
|
||
| 1. On your local machine, with the [Sourcegraph CLI](#create-a-batch-change-with-the-sourcegraph-cli) | ||
| 2. Remotely, with [server-side execution](/batch-changes/server-side) | ||
| When the spec is ready to run, ensure the preview is up to date and then click **Run batch spec**. This takes you to the execution screen. On this page, you see: |
There was a problem hiding this comment.
If we have documentation for previewing, maybe link out to that here? As a reader, I asked myself "how do I ensure my preview is up to date" when I read this 1st sentence
|
|
||
| ### Previewing and applying the batch spec | ||
|
|
||
| On this page, you can review the proposed changes and the operations taken by Sourcegraph on each changeset. Once satisfied, click **Apply**. |
There was a problem hiding this comment.
"taken by Sourcegraph" seems unnecessary here IMO
|
|
||
| ## Viewing batch changes | ||
|
|
||
| You can view a list by clicking the **Batch Changes** icon in the top navigation bar: |
There was a problem hiding this comment.
View a list of what? (Just being pedantic here to highlight that it's a little unclear)
There was a problem hiding this comment.
Added Batch Changes to clarify
|
|
||
| ### Title-based search | ||
|
|
||
| You can search through your previously created batch changes by title. This search experience makes it much easier to find the batch change you're looking for, especially when you have large volumes of batch changes to monitor. |
There was a problem hiding this comment.
Nit: I'd remove "much" from "much easier" b/c it implies finding your spec w/o search is a huge PITA, which I don't think we want to promote
|
|
||
| ## Filtering Batch Changes | ||
|
|
||
| You can also use the filters to switch between showing all open or closed Batch Changes. |
There was a problem hiding this comment.
Nit: I'd remove "the" from "the filters" (and "the" from "the keywords" above) b/c it's just unnecessary to specify IMO
|
Hi everyone, for now I have converted it to a draft PR till I point it to the 6.6 release branch. |
3 participants
This PR updates the documentation for the batch spec library following the introduction of batch spec templates.
Most notably it
For easier reviewing of the new content, I created two PDFs:
Batch Changes site admin configuration reference - Sourcegraph docs.pdf
Creating a Batch Change - Sourcegraph docs.pdf
Pull Request approval
You will need to get your PR approved by at least one member of the Sourcegraph team. For reviews of docs formatting, styles, and component usage, please tag the docs team via the #docs Slack channel.