Marfeel Docs

# Overview

Welcome to Marfeel Docs, the place where you will find in-depth technical documentation about the Marfeel Platform.

The documentation is structured by functional areas or projects and having in mind its scope and who will be consuming it.

# Documentation ownership

Having world-class documentation is not an individual member's effort, it's a team and company effort. This means that everyone on a team is responsible to create and update the documentation.

Contribute

Want to contribute and don't know where to start? Check out the Quickstart guide!

# MarfeelDocs flow

MarfeelDocs follows a GitHub centric workflow to achieve several foundational goals.

It's very common that a project and its documentation get out of sync and that they move in different paces, frustrating both readers and writers. To avoid this situation MarfeelDocs documents are in the same GitHub code repositories as the source code, creating a very tight relationship across code, documentation, engineers, and product managers.

Making GitHub repositories a one-stop-shop for source code and documentation allows some interesting workflows:

  • Updating the documentation is part of any PR. All developers must make sure that the documentation is not obsolete when contributing changes or new code.
  • Checking the docs becomes an active part of the PR workflow, giving full ownership to the teams.

Last, by having the documentation on the same code repository in markdown format makes the workflow more developer-friendly. Developers can scan through the docs without leaving the IDE.

# Documentation scope

  • Public Docs: This documentation is public and will be accessible publicly inside and outside Marfeel.

  • Internal Docs: Internal docs are meant to be documentation oriented to developers, explaining the insights of the Marfeel platform, its exposed APIs, how to debug certain parts of the code... This documentation is for Marfeelers only and becomes accessible once you've logged in the MarfeelDocs platform.

It's the URL that determines if a document is public or private. Read more in the Private Pages guide.

Open-source philosophy

We are assuming not all Internal docs are interesting for all Marfeelers. However, those documents will always stay freely available to all Marfeelers.

# Types of documents

As you read the documentation you'll find different types of documents:

  • Explanation: Understanding-oriented articles, meant to clarify concepts on a particular topic.
  • Guide: They provide a step-by-step for Marfeel workflows, common tasks, tutorials and how to’s.
  • Quickstart: It's a short version of a Guide meant to make developers familiar with the project as soon as possible.
  • Reference articles: They cover different concepts and techniques without the step-by-step context provided in a Guide. In general, they try to explain how a System, a building block, or a more complex concept work. They are grouped in the sdk-reference folder of each section.
  • Development: Projects can expose a Development section exposing all the internal details of how to download the source code, compile and test along with documentation aimed to project developers. They can be found in the development folder of each section once logged in.
  • Glossary: A brief dictionary with important definitions related to its section.

# Start contributing

Anyone with access to GitHub can contribute to MarfeelDocs.

Get started by reading the Quickstart article, which contains the minimum information to become a contributor.

To become a champion contributor though, we recommend you read the documents below. There, you'll learn all details about contributing.

  • Contributing: Learn how you can contribute to MarfeelDocs through a git-based approval workflow, how the documentation is structured, and where are the files stored.

  • Styling and markup: Learn the basics of Markdown, a lightweight markup language that you can use to add formatting elements to plaintext text documents.

  • Writing conventions: Learn the different conventions used in the docs and how to add metadata to your documents via the Frontmatter

Marfeel Docs uses Algolia (opens new window) as a search engine, offering full-text, numerical, and a faceted search, capable of delivering real-time results from the first keystroke. You can search for Documentation, References, Guides, Flags, etc.

Typo Tolerance

Algolia is configured so it interprets typos, displaying results even when the search word is not typed properly.

← Quickstart →