Docs As the Code, Docs In the Code At New Relic

func (c *Command) Run() (string, error) {



   // set the locale BLAAARGH

— An old comment in our source code

Software is made of words. Some words, such as UI text or command-line messages, are for human-computer interaction; some, like API calls and error codes, target other software; and some form the documentation—README files, user guides, online help, and more.

The vast majority of words in software, though, are its source code: those words that make it run.

Code, too, contains human-readable text. Consider any piece of software: Whatever the programming language (except maybe Malbolge and its esoteric companions), chances are that you'll find plenty of meaningful and useful words in the source:

• Embedded reference docs, which can be used to build docs automatically (for example, GoDoc, Javadoc, GraphQL, and OpenAPI)
• String literals, from log messages to errors to input prompts
• Examples and comments in configuration files
• Names of CLI commands, variables, functions, and methods
• Comments in the source code (like the one I quoted above)

Now that we’ve made our software open source, the idea of docs in our code has even greater importance to us.

When words in code are forgotten

If code isn't documented, it doesn't exist. In many cases, code may lack embedded documentation, making it hard for developers to understand how it works or is intended to be used.

But that's not the only thing that can go wrong: Undocumented API schemas result in poor user experiences when loaded into API explorers; configuration files without comments are hard to tweak, and badly-written errors can make troubleshooting needlessly difficult. Plenty can go wrong when software lacks embedded documentation.

At the end of the day, our software is also measured by the quality of its words, the way it speaks to users, and how well it’s documented. Great docs unlock a great developer experience. If we expect our dev community to pull our code and enrich it, we should ensure it’s well commented and documented.

How the Product Language team contributes to docs in code

It’d be a long blog post if I detailed every bit of our work, so here are a few recent examples of docs-in-code work that the Product Language team has accomplished:

1. In preparation for the open source release of the Infrastructure agent, we reviewed the entire code base for typos, formatting issues, forbidden words, and sensitive information in code comments. At the same time, we fixed capitalization issues and grammar in the CLI and debug messages, and edited the README.
2. We regularly edit NerdGraph GraphQL schemas for embedded documentation. Docs in schemas are key to good GraphQL experiences; see, for example, the screenshot below: All fields have basic reference documentation. The same applies to OpenAPI specifications for REST APIs.
3. We also write and edit comments in sample configuration files that help users install our agents and integrations faster. The sample configuration file for the Windows services integration, for instance, provides a brief explanation that builds on the existing documentation, so that users in a hurry can still get some guidance even if they skip our docs.
   

   # To include services, create a list of filters to be applied to the service names.
   
   # Services that find a match with any of the matching lists are included. By default,
   
   # no service is included.
   
   #
   
   # Currently, only windowsService.name metadata is supported for filtering.
   
   # Prepend "regex" to indicate that the pattern is a regular expression.
   
   #
   
   include_matching_entities:
   
     windowsService.name:
   
       # - regex "^*$"
   
     # - "ServiceNameToBeIncluded"

Help us do docs in code

We’re dedicated to bringing clear, concise, and thoughtful documentation to our open source projects—from our agents to New Relic One applications to our open source and developer sites.

If you have any questions or needs concerning the docs you encounter in our code, don't hesitate to reach out to us in the appropriate repo with a comment or pull request.

Happy docs-as-coding!