Skip to content

Developer Center 101

Jump to bottom
Jorge Gomez Sancha edited this page Feb 26, 2018 · 4 revisions

This page describes the basics about the new Developer Center. It explains the genesis of the project, the main principles, the process to add new components to the project and what place the Developer Center occupies in a new approach to content experience in CARTO.

Genesis

Contents regarding Engine and, in general, any technical part of the CARTO stack have been usually understood in CARTO just as technical documentation. In that sense, "Technical documentation" has never really been understood as part of the user experience. Until now it has been called just "documentation" and you could find everything in this URL on the website: Docs.

That approach has a lot of implications in terms of user experience:

  • It doesn't allow to build a specific developer experience. "Docs" contents are presented with other types of contents like "Resources", "Webinars", or just "Learn".

  • It doesn't give a good understanding of the different types of components of the stack. Everything is just "technical documentation", and thus a component like CARTO.js is taken just as another component like "CartoCSS".

  • It doesn't build a good reading experience. Components' contents are divided into articles not according to the developers' perspective.

  • It doesn't build a good coding experience. There aren't real examples integrated into the documentation so that developers can learn while playing with them.

That approach has implications in terms of internal processes as well (and these processes affect the developer experience too):

  • "Docs" contents are not taken as a part of the developers' work. The process was designed more top-to-bottom and lead from a marketing perspective, having a technical writer as the main contributor. That causes two important problems: contents are usually outdated, developers are not involved.

  • CARTO developers don't eat their own food. Since these contents are not taken as a part of their work, they don't use them either.

  • Contents are not part of our Open Source philosophy. We manage some of the contents into the component's repository, and part of them into the "docs" repository. Issues regarding contents are managed on the last one, and thus we lack visibility and the capacity of receiving contributions.

The new approach embraces the "developer experience" as the main goal, trying to address all of these issues.

Main principles

  1. The developer experience requires an entire, specific information space. It isn't under "Learn". It doesn't share common breadcrumbs or any other common component with other types of contents. It deserves a specific name: "developer center", "CARTO for developers", "developer tools", etc. The version in progress on staging is here: https://cartodb.github.io/documentation/

  2. The developer experience requires an easy introduction to the global stack, besides the specific information available for each component. The key concepts must explain the transversal aspects of the stack. The specific information of each component must explain everything within the component.

  3. The developer experience requires an easy/visual understanding of the organization of the stack. So, we need to separate components according to its nature: libraries, APIs, flavors, etc.

  4. The developer experience requires a consistent organization of contents within each component: contents to learn step by step (guides), contents to learn by doing (examples), contents to dig into details (full reference), contents to learn about issues (support, browser support, errors support, etc.). Each kind of content must offer an entire experience, so if you are browsing the full reference API you need to find in there everything you need. And so on with the rest of groups of contents. See an example here: https://cartodb.github.io/documentation/carto-js/

  5. The developer experience requires a consistent way of scaling the contents. So, the containers for each component must be prepared to work well with sparse contents at the beginning and to grow well with additional contents. Developers must know that if they regularly visit a component microsite, they will find whatever new information has been added in a consistent manner.

Process to add a new component

Once you want to add a new component to the new developer center, you must take into account some principles, and follow some steps:

  1. Developer Center Repository is an orchestration repository, it doesn't host the totality of the content; the content specific to each component must be in the component's repository, so that it can be used to populate the Developer Center but could also be used for other purposes (like a "man" page, or other)

  2. Contents in the component's repository must follow a structure according to the different types of contents. There must be a docs root folder and it can optionally have guides, examples, full reference and support folders under the root folder.

  3. Currently, the Developer Center Repository fetches contents with .md and .rst formats. Every piece of content must be created in one of these formats.

  4. Currently, the Developer Center Repository can build Full Reference APIs out of JSDoc and OpenAPI specification. Every API Reference must be in any of these formats.

  5. As soon as you have the first contents on the component's repo you want to add, following the structure mentioned above, you need to talk to @cillas, so that she can add the orchestration piece into the Developer Center Repository. Once it starts working, you will have a microsite for the component, with its own menu, the first contents, etc.

Cillas is the lead developer of this project. She is the contact for any issue/doubt regarding the process, how the orchestration repo works, etc.

Place of the Developer Center into the content experience at CARTO

Now that we are aware of the importance of contents as part of the user/customer experience in any CARTO product, we have started the discussion about other specific information spaces that would help a lot.

  • It's clear enough that we make a lot of (and great job of) helping users/customers through SupportBee, our main official communication channel. We are going to put together a Help Center to cover this, in a public and consistent manner.

  • We do great efforts helping our users/customers with training as well. It's part of Customer Success work, but of the Solutions Team too. We are going to improve our current Guides information space, with guides pretty focused on tasks and problems our customers daily face.

  • We will probably setup a Training Center as well, but not as an information space, in terms of contents of our training, but rather as an entry point to receive leads. We need to expose publicly that we do training, that we have professional services in there, etc.

So, it's good to understand the Developer Center from this global picture.

Clone this wiki locally