apidays New York 2023 - Use What You've Got, Sarah Simpers, MongoDB

apidays New York 2023
APIs for Embedded Business Models: Finance, Healthcare, Retail, and Media
May 16 & 17, 2023

Use What You've Got: How Incremental Updates to our Automated CLI Docs Improve the Developer Experience
Sarah Simpers, Senior Technical Writer at MongoDB

------

Check out our conferences at https://www.apidays.global/

Do you want to sponsor or talk at one of our conferences?
https://apidays.typeform.com/to/ILJeAaV8

Learn more on APIscene, the global media made by the community for the community:
https://www.apiscene.io

Explore the API ecosystem with the API Landscape:
https://apilandscape.apiscene.io/

Transcript

1. Use What You’ve Got How Incremental Updates to our Automated CLI Docs Improve the Developer Experience Sarah Simpers Senior Technical Writer, MongoDB WELCOME
2. You can improve your DX using code you already have.
3. Devs start and keep using the product Internal devs can easily add to docs More contributors and faster results
4. Our Results 69% more CLI MAU 61% more orgs created 20k tech writer additions
5. Three Incremental Updates CLI everywhere Give the output State required roles
6. Understanding our CLI stack Atlas Administration API API for MongoDB Atlas mongodb-atlas-cli repo CLI code base cobra2snooty repo Output docs to rST docurl Fetches code files for docs repo
7. Update #1: Atlas CLI everywhere
8. Use existing CLI docs Syntax ------ .. code-block:: :caption: Command Syntax atlas accessLists list [options] .. Code end marker Pull the code block into Atlas docs To {{task}} using the Atlas CLI, run the following command: .. literalinclude:: {{command}}.txt :start-after: :caption: Command Syntax :end-before: .. Code end marker :language: sh :dedent: Atlas CLI everywhere
9. [15:14:35] Some versions are out of date. [15:14:35] mongodb/mongodb-atlas-cli [15:14:35] Updating mongodb/mongodb-atlas-cli@v1.6.0. [15:14:35] mongodb/mongodb-atlas-cli updated to @v1.6.0. > cloud-docs git:(my-branch) None! docurl updates DEV WORK > cloud-docs git:(my-branch) docurl docurl [15:14:37] Fetched 250 files. update fetch
10. Atlas CLI everywhere At every Atlas CLI release, docurl updates 200+ code snippets in the Atlas docs automatically.
11. Update #2: Give the output
12. Call existing CLI variable var createTempl: "Deploying cluster `{{.Name}}`.\n" … Annotations: map[string]string{ "output": createTmpl, }, Pull the variable into the template output := strings.ReplaceAll(cmd.Annotations[ "output", "{{.", "<") … buf.WriteString(outputHeader) buf.WriteString(` If the command succeeds, the CLI returns output similar to the following sample. .. code-block:: `) fmt.Fprintln(w, " "+output) Give the output
13. Devs add outputs DEV WORK Annotations: map[string]string{ “output”: listTemplate, },
14. Give the output We reuse the variable for the output in the CLI to show the output in the CLI docs.
15. Update #3: State required roles
16. Define the template RequiredRole = "To use this command, you must authenticate with a user account or an API key that has the %s role." Add required roles from the spec func ListBuilder() *cobra.Command { cmd := &cobra.Command{ Long: fmt.Sprintf(usage.RequiredRole, "Organization Member"), State required roles
17. Long: fmt.Sprintf(usage.RequiredRole, "Organization Owner"), Devs add roles DEV WORK
18. State required roles The Atlas CLI docs tell you the required roles for every command using consistent language.
19. Three Incremental Updates External Devs Internal Devs Tech Writers
20. Start improving your DX using code you already have!
21. Thank you for your time.