# Content Re-Structuring As I start in my new role working on the Yearn DevDocs, I figure that making a splash and proposing big changes would be more fun than just continuing incremental changes. The proposal below is based on my recent experience with the docs, prior experience with DAOs, and my understanding of Yearn. Some of my intuitions here could be wrong and I encourage feedback, corrections, and disagreements with by proposal. ## Introduction The Yearn dev-docs are a living and evolving document repository that have changed over years as Yearn has changed. They are relied on as the place where developers and non-developers alike can find information on the workings of Yearn. They are like a swiss army knife, built to handle many tasks and needs. But swiss army knives often suffer from not being very good at doing any particular thing. I am proposing to improve the usability of the docs by focusing more specifically on the different user stories and use cases of those who we expect to read the docs. ## Current Structure The Docs are currently split into 6 headings: - **Introduction** - This section is focused on introducing what Yearn is, the products that Yearn has created, and how to use those products. This is the most "user-focused" section of the docs and is written in a less technical way. - **Develop** - This section, as the name implies, is focused on the developer experience for yearn, how to build vaults and strategies, and other information about integrating yearn. - **Smart Contracts** - This section is similar to API documentation for developers, giving detailed descriptions of the functions and parameters for the various Yearn Smart Contracts. It is inherently developer focused, and is linked to from the developer section as well as via the main navbar. - **Contribute** - This section is focused on those who wish to contribute to Yearn, the DAO. It also has sections on information about the DAO and YFI, and information on contributing to the docs themselves. - **Resources** - This section is a grab-bag of other things that didn't seem to fit in the prior categories. A FAQ, links, info about risks, deprecated projects, links to a github with 3 year old financial statements. It is very unclear who this section is for other than those who don't know what to do with some items they don't want to throw away. - **Security** - The security function has useful information about the multi-sig, testing, audits, and other information, but it feels incomplete and like a section that was put there because no one could figure out where else it should go. The biggest issue I see with the current structure is that it is often not clear where different users need to go to get information. There landing page that has 2 categories: "learn" and "Build", and they each have 3 subheadings that go to different parts of the docs. But these links feel arbitrary. The "Vaults and Strategies" link in "Learn" goes to the develop docs while the "veYFI" link in "Build" goes to the introduction docs. This landing page does not reinforce the structure of the docs and seems instead to be a guess at what a visitor might be most interested in looking it. ## Proposed Layout/Content Changes To improve the docs, I recommend focusing on creating clear sections that are catered toward specific use-cases of people using the docs. The primary user group seems to be Developers, but because there isn't much information about Yearn and its products on the main website (https://yearn.fi), these docs also need to serve those who use the products and those who want to participate in governance and/or contribute. While each of these users may have some overlap, splitting the docs into these 3 sections will immediately make them easier to navigate. - **User Docs** - This section would focus on the products and the "what and why" of Yearn. What is it? What does it build? Why does it build these things? Why does that matter to me as a user looking to put my crypto to work earning yield? This isn't so different from the current "Introduction" section. - 1 section about the DAO and mission, similar to the blue pill. Maybe a simplified version of that. Tell the story - 1 section with all the products and general info about them. Enough for your average user. Links to dev docs sections for those looking to go deeper. - 1 section with walkthroughs related to user experience and articles with useful information. - links to risks section and smart contracts in sidebar - **Developer Docs** - This section would focus on Builders and more detailed information about the products, smart contracts, tools, and other developer-centric information. - This could either be organized by product line (yVaults V2, yVaults V3, Liquid Lockers, tools, etc) or by builder type (Smart Contract Dev, Front End Dev, Data Analysis) - This would also include walk-throughs and other useful information for developers looking to start building. - Smart contracts live here by product line. Can be linked to from other sections but they are developer tools. - **Contributor Docs** - This section would focus on information about the DAO and about contributing to it. - General info about contributing. By the time a potential contributor arrives here they probably know what yearn is and are looking for information about how to actually help out. Surface what the DAO actually wants help with. My guess is that the amount of outside, unsolicited contribution is much lower than it was 3 years ago. The docs should reflect the reality of how the DAO wan't contributions. - Information on Governance and YFI. - Information useful for YFI holders. I expect there will also be a number of pages that are hard to categorize and/or want to live in all 3 sections for easy access. These could be grouped in the sidebars of all 3 sections and link to the same documents. This would be for things like important tools or sites, smart contracts, etc. ## Other Potential Changes ### Tight Coupling to Github Repos For the Developer Docs sections, some of the documentation may also be useful to developers working directly in the respective git repos (diagrams, overviews, etc), and other docs may live there natively (Tech Specs for things like V2 and V3 vaults). In order to minimize redundant documentation and the potential for conflicting information, **is worth considering whether some files should be linked to the docs directly from other repos?** I have previously used [this plugin](https://github.com/rdilweb/docusaurus-plugin-remote-content) to import .md files from remote repositories into a docusaurus site. The workflow would be something like this: - Certain documents would live in the respective yearn github repositories and be editied there. For example the [V3 Tech Spec](https://github.com/yearn/yearn-vaults-v3/blob/master/TECH_SPEC.md). - The devdocs would be set up with a plugin like the one above that would pull the .md file into the devdocs at build time. - All sidebars and links would be the same, but contributors would need to remember that edits must happen on the remote repo and not on the local copies. #### Pros - Content lives in one place and is easier to keep everything in sync and current. - Content is shared between the docs and github repos and is available to both when used as expected. #### Cons - Added technical complexity on the devdocs repo. - Additional dependency could fail - harder to get contributors to understand where everything is. I'm curious to hear outside opinions on whether this would be a good change or not. ### Remove Native Docusaurus Versioning I have a [pull request ready](https://github.com/yearn/yearn-devdocs/pull/428) that simplifies the way we do versioning in docusaurus. TLDR is that with the release of V3 vaults, there are now competing product versions so the versioning system we are using requires a rework. You can play with a mockup here: https://yearn-docs-4d3kh8t0n.yearn.farm/smart-contracts These changes wouldn't be affected by the larger content restructuring proposed above. In context of the larger restructuring, the smart contracts and other pages shown in the `Smart Contracts` section would move to the developer docs. How we do versioning is a separate decision. ## What do you think? I'd love to hear from existing contributors about what they want to see improved and/or changed with the docs? Do you use them? What for? What would the ideal documentation website look like? Have you seen good examples? Please reach out to me to discuss!