MyST Core Design Philosophy

--- mep: id: XXX author: - Please add your names here! created: "2022-11-XX" type: Process status: Active discussions-to: https://github.com/executablebooks/myst-eps/discussions/4 --- # MyST Core Design Philosophy Markedly Structured Text (MyST) is intended to provide: 1. A human readable text format for writing technical and scientific documentation. 2. A specification for an abstract intermediate representation, independent of the input and output formats. 3. A specification for a reference parser implementation, which can be used to convert from the text format to the abstract intermediate representation. 4. A specification for a reference renderer implementation, which can be used to convert from the abstract intermediate representation to a variety of output formats. ## Guiding principles and constraints In running this project, we aim to adhere to several principles that we believe will result in higher-quality technology that aligns with the core principles of the open source community. Here are a few key components: - **Give equal support to casual users and power users.** Complicating the feature space to support a “power user feature” should be done with great care. - **Build modular components that are useful elsewhere.** Rather than building a single vertical stack, find parts of the workflow that naturally separate. Create modular tools for these parts so that they may benefit the community outside of the context of building interactive books. - **Use pre-existing technology where possible.** Rather than re-inventing the wheel, make every effort to utilize pre-existing open source tech. - **Use pre-existing standards where possible.** In the event that we must create new patterns of content creation or tooling, utilize prior art in the open source community as much as possible, especially when it comes to markup languages. - **Contribute improvements upstream.** Where we utilize pre-existing tools, contribute improvements to them as we build off of them for this project. - **Design for the future.** While we have a bit of funding now, it won’t last forever. This means the technology should be easy for potential developers to read, understand, and modify/improve. - **Users should not need to know anything about the build system.** If they want to dig into the guts of our infrastructure, they can, but knowledge of Sphinx, Latex, and so on should not be a requirement. They should only need to use a simple tool to control the process. - **Don’t try to do everything.** Focus our tools on publishing computational documents with reasonable choices made for the user.