Technical docs

[doomling]

Motivation:

Rebuild Decentraland’s documentation hub to make it simpler to maintain and keep up to date. Automate content scrapping for technical documentation to reuse existing docs for each repository so not every bit needs to be created and uploaded by hand.

How-to:

Create a static JAMstack site that can easily be deployed to a CDN. Everything is generated at build time, there are no external calls or data revalidation.
The project has a configuration file were repositories can be added to the scrapping list. *.md files are scrapped from the ”docs” folder on each repository. Subdirectories are supported and scrapped as well.

Frontmatter data will be used to add metadata to each file. Files that don’t present the minimum required* metadata won’t be scrapped.

Contributing to docs workflow (WIP):

• Push *.md files with documentation to each repository included the required frontmatter metadata
• PR to the docs repository adding the desired repository to the config file
• Docs will be rendered in the next project build

Open questions

• Minimun frontmatter data to render a file?*

• Do we want permalinks? How should we make their syntax easy for external contributors?

• Should we expose a mini-index on the right-hand side of every page?

• How should each project structure their documentation folders in their repo for the scrapping process to interpret them correctly?

• Should the search bar make a visual distinction between results that are in a different section from the current one?

• What sections and new content should we include in player docs? Several products are totally or partially lacking docs, like the DAO, Marketplace, Builder, Events page, etc. How should we structure this content?

• Add yours!

Closed questions

[menduz]

Question: How should each project structure their documentation folders in their repo for the scrapping process to interpret them correctly?

[menduz]

For generation of nav structure I've seen two approaches mainly:

1. Sidebar is a MD file, the structure is not inherited from the file structure (mdbook SUMMARY.md)
2. Sidebar is inferred from the files (many others)

I think both approaches have their pros and cons.

SUMMARY.md

Pros:

• Maximum flexibility
• Allows to set titles != frontmatter.title
• Allows for extra docs files (even WIP) without referencing them in the menu bar
• Allows for custom hierarchy of contents, no matter where files are located
• Files can be located in any folder, project dependent, allowing repos to have their own structure without sacrificing navegation

Cons:

• Manual editing of SUMMARY.md may lead to errors
• Manual editing itself

Auto generated structure based on folders + frontmatter

Pros:

• Convention over configuration, the folder structure leads the final content structure
• Less operative work (No extra files)

Cons:

• Ordering/filtering files in the sidebar bound to the file names
• Makes it hard to move files to different folders without affecting navigation
• Less flexibility in sidebar
• To not show elements in the sidebar, frontmatter options may be used

After writing the pros/cons I think the SUMMARY.md+slug/permalinks approach may be my favorite

[doomling]

So, in addition to a PR in their own repo + changes in config it would require contributors to add the entries into SUMARY.md? then we consume the slugs/permalinks from frontmatter

[menduz]

I think we may have a summary.md in each <repo>/docs/summary.md for clarity, not in the root docs repository, to prevent double PRs