MLabs - Dev Documentation Drive

[IMPACT] Please describe your proposed solution.

Market

dApp builders on Cardano.

Problem Space

When building a dApp on the Cardano Network, there are several major hurdles to overcome, which are solved through strong documentation in other ecosystems. Very early questions such as 'What tools and libraries should I use to build a production-ready app?' are often tough to answer. This compounds knowledge among the experienced developers and prevents new developers from learning the lessons of previous projects.

This leads to a great deal of lost time and resources across many projects. Projects may need to experiment with and ultimately abandon tools or implement their own tooling. Developers may struggle through under-used parts of a tool or library, slowing their productivity. Documentation can also go stale and become inaccurate as tools grow and change.

What does high-quality documentation look like?

reference: https://diataxis.fr

Strong documentation will typically reflect a mix of four categories:

1. Tutorials
2. How-To guides
3. Explanations
4. Reference

Tutorials are designed to introduce a piece of technology to the user. They often reflect the most common use cases and must maintain simplicity to avoid overwhelming the learner. For example, an easy introduction to working with the tool without unnecessary details.

How-To guides assume some familiarity with the technology or tool and address important features and use cases or integrations with other tools that might not be obvious after the first tutorials.

Explanations help users to understand exactly why a tool has a certain behavior, addressing lingering questions and non-intuitive aspects of the technology. Potentially helping contributors to the project have a better understanding of the project's inner workings, or helping a developer move from a beginner to an intermediate user.

Reference material is about maximum detail about the project, intended for troubleshooting, advanced configuration, or a fast lookup for an immediate problem that may be found.

There are some other properties that good documentation ought to have to maximize its utility:

1. Searchability
2. Discoverability
3. Clarity
4. Readability
5. Accuracy

Searchability - The documentation has internal search-by-keyword and is laid out in an organized way so that a developer can quickly find the article(s) relevant to their current effort.

Discoverability - The documentation can be located through Google and other search engines easily, the documentation resource is found on resource lists (such as Essential Cardano), readme files for relevant projects, and other locations. If nobody can find your documents, they aren’t very useful.

Clarity - Concepts must be plainly laid out, and in some cases, explained multiple different ways, so that users can gain a better understanding of complex concepts. Illustrative examples can offer even greater benefits.

Readability - Providing a consistent glossary of terms, explaining those terms, and providing references can help users gain a better understanding faster, especially if the terms used are aligned with those used in other knowledge bases across the ecosystem. This can also apply to code style in examples, being very explicit and optimizing code so that its meaning is explicit.

Accuracy - Documentation can become outdated very quickly, as bug fixes and feature improvements land, documentation can be an afterthought. Sometimes tests can be introduced to ensure that documentation aligns with the current implementation. Sometimes users need to make sure they are viewing the correct version of the documentation for the software version they are using.

As an example of a documentation project which exhibits these properties, The Mozilla Developer Network provides documentation for web and browser technology. This is a shining example of excellent developer-directed documentation which can radically improve development times on a range of projects.

In the fast-moving world of Cardano dApp development though, we have a different set of tools that we can currently leverage:

1. Haddock documentation (for Haskell tools)

2. Specification documents

3. In-repo docs

4. Knowledge-hubs

5. Blog posts

Each of these offers less-than-ideal tradeoffs for discovery and searchability, and this leads to a sort-of folklore of knowledge, found in obscure corners of documentation, which is often central to the real use of those tools.

In short, our work is cut out for us if we want to build the level of documentation necessary for Cardano to grow.

[IMPACT] Please describe how your proposed solution will address the Challenge that you have submitted it in.

We want to commit to making serious improvements in Cardano ecosystem documentation.

This will include:

• Updating haddock documents to be in line with the specifications so that developers can avoid working with specification documents in favor of the more searchable haddock documents across the entire Cardano/Plutus stack.
• Contributing documentation to several key ecosystem components, with a focus on discoverable tutorials, highly searchable reference materials, and explainer blog posts.
• Building better tutorials to understand on-chain and off-chain architecture, enabling dApp developers new to the ecosystem to more quickly understand the landscape and help them make critical early decisions.

Key software projects we wish to contribute to as part of this effort include:

1. Cardano (including cardano-node, cardano-api, cardano-cli, and other components)
2. Plutus/Plutus-apps (Including PAB)
3. Plutarch
4. Plutip
5. Cardano-serialization-lib & Cardano-multiplatform-lib
6. Blockfrost & Ogmios
7. Oura & Carp

Together, these applications represent the most common building blocks for production dApps on Cardano today.

To keep these resources discoverable, we may also make contributions to multiple documentation projects, such as:

1. Essential Cardano
2. Awesome-plutus
3. The Plutonomicon

How will these resources help Cardano?

We want to provide significant improvements to documentation so that developers across the Cardano ecosystem can move faster, get stuck less, and ultimately ship products for less.

[IMPACT] What are the main risks that could prevent you from delivering the project successfully and please explain how you will mitigate each risk?

Of course, maintainers for projects not directly run by MLabs will need to agree with our approach to documentation for our work to be merged, so it’s critical to involve them in the process. Long-term, as new features are added or new tools introduced, the documentation will also need to be updated.

[FEASIBILITY] Please provide a detailed plan, including timeline and key milestones for delivering your proposal.

3 Months:

Completed efforts:

• Move spec information to developer-facing searchable docs
• Publish new Tutorials and Explainers for Plutarch

6 Months:

Completed efforts:

• Tutorial: From Blockfrost to the Node
• Tutorial: Oura in Practice
• Plutonomicon Updates

[FEASIBILITY] Please provide a detailed budget breakdown.

Hours involved: 750

Total: $60,000

Breakdown:

Feature Total Time

Cardano & Plutus - Make information found in specs easier to find: 210

Plutarch - Tutorials & Explainers: 100

Tutorials - From BlockFrost to the Node, building a Transaction: 100

Tutorials - Oura In Practice: 80

Plutonomicon Update - revisions & corrections: 50

Plutonomicon Update - new designs & in-depth articles; 100

Plutonomicon Update - script optimization guide: 60

Subtotal: 700

Change Budget: 50

Total Time: 750 hours

Total Cost: $60,000

[FEASIBILITY] Please provide details of the people who will work on the project.

MLabs

MLabs has quickly become one of the premier development firms in the Cardano Ecosystem. We are an IOG Plutus Partner and work regularly with IOG to develop the Cardano blockchain and ecosystem. Our team is composed of talented developers who have helped build community projects such as:

• Liqwid
• SundaeSwap
• Optim
• Many others

Through our work with early-stage projects, we have one of the largest groups of Haskell / Plutus developers in the community.

Website: https://mlabs.city/

Core Team

Las Safin - Head of Research

Las is a software engineer and formal methods specialist who is experienced with dependently typed languages such as Idris and Agda and who is interested in Cedille. At MLabs, he helps manage Nix environments for use in development and writes application specifications as well as compilers.

Las has also made significant contributions to Cardano tooling. Most notably, he is the creator of Plutarch. Plutarch is a typed eDSL in Haskell for writing efficient Plutus Core validators. Plutarch significantly lowers the resource demands of validators written in the eDSL while providing developers more fine-grained control of the Plutus Core generated. See the GitHub link for more information.

Vlad Posmangiu Luchian - Project Manager & Architect

Vlad is a software engineer working with Haskell. At Mlabs, Vlad works on designing and delivering a diverse range of DApps including DEXs, Oracles, and NFT Marketplaces. In his spare time, he takes a keen interest in researching type and programming language theory.

Viet Tran - Project Manager

Viet has an undergraduate and master's degree in Mathematics alongside a Ph.D. in Theoretical Physics. He previously worked as a quant, writing Python/Cython code to model the outcome of sporting events through optimizers, Markov Chains, and various probability distributions. He acquired an interest in category theory, functional programming, and blockchain technology in recent years. He has 12 months of experience in Haskell, Plutus, and Purescript combined.

Rory Tyler Hayford - Delivery Manager

Rory is a linguist-turned-developer and programming polyglot. His development career began with the web, and he has experience with both backend and frontend development. His initial forays into functional programming several years ago soon turned into a profound and lasting passion. He has a strong background in functional programming and reproducible build systems with a focus on Haskell, Nix, and Purescript. He is also the author of a handful of open-source Haskell libraries.

[FEASIBILITY] If you are funded, will you return to Catalyst in a later round for further funding? Please explain why / why not.

This proposal is complete unto itself, so the indicated documentation will be delivered without additional funding. However, should the project be well-received, we may extend its lifespan further into the future. In so doing, we may possibly seek additional Catalyst funding in future rounds.

[FEASIBILITY] Are you or any member of your team working on any other proposals in this Fund9?

[FEASIBILITY] Are you or your team working on any other proposals from previous Funds?

[AUDITABILITY] Please describe what you will measure to track your project's progress, and how will you measure these?

Essentially, we will track the engagement metrics of the documentation we publish. This includes:

• number of issues raised
• number of questions asked
• any citations or backlinks
• likes, kudos, etc.
• general usefulness and reception of the documentation
• associated comments and questions

[AUDITABILITY] What does success for this project look like?

Intended Fund – Fund9: Developer Ecosystem

Challenge Question: “How can we create a positive developer experience that helps the developer focus on building successful apps?"

Project Impact: High

1. Best Practices: By helping developers choose the best tools for their projects, and understand how to get the tools working together, we reduce costs and improve the developer experience across the ecosystem.

2. Setting Standards: By contributing documentation upstream to existing projects, we help improve the standards for documentation in those projects going forward as well. If a project has out-of-date documentation or removes critical documentation, it is more likely to receive feedback from its users about the problem. Many early contributors to open source projects work against docs, and having a strong documentation base within a project can be an excellent way to gain external contribution. Newer projects can take a queue from other projects in the ecosystem with excellent documentation and work to build their own.

3. Reliability: By documenting the usage of tools and apps, we encourage developers to actually use them. Both the process of creating documentation as well as the influx of users can help with critical bug discovery, ultimately leading to a more reliable ecosystem for developers.

Contributions from this project will be reported directly to the Catalyst team, and listed resources will be updated seamlessly, additionally as milestones are completed, MLabs will engage the Cardano community through social media as well

[AUDITABILITY] Please provide information on whether this proposal is a continuation of a previously funded project in Catalyst or an entirely new one.

This is a new proposal.