Ideas for restructuring documentation site for Lockup and Flow

[smol-ninja]

The current doc's structure is inspired by Uniswap keeping in mind only 1 product. That structure now seems to be outdated. For example, Uniswap also allows trading NFT (thanks to Genie acquisition) on their platform, but their documentation has no information on Genie. Given that, soon we would have more than 1 protocol (Lockup, Flow, Solana Lockups etc.), its time to think about refactoring the structure of the documentation site.

---

I looked at several options and balancer docs stood out for me: https://docs.balancer.fi/.

• Every page is always under a sub-category.
• Developer guides and technical references are separate categories. In our case, they are merged under Contracts category. Having them separate is useful to include multiple protocols.

Similarly, Sablier docs can be refactored as the following:

- Top bar
    - Concepts
    - Developer Guides
    - Technical References 
    - Apps
    - APIs

- Concepts
    - What Is Sablier? (includes content from The Sablier Protocol)
    - Streaming
    - Use Cases
    - Lockup
    - Flow
    - Common pages such as Fees, NFTs etc.
    - Security/Audits
    - Governance
    - Glossary

- Developer Guides
    - Lockup (overview, content from Guides, Gas benchmarks, deployment addresses, older versions)
    - Flow (overview, content, gas benchmarks, deployment addresses, older versions)

- Technical References
    - Lockup (content from smart contract references)
    - Flow

- Apps
    - Overview
    - Lockup
    - Airstreams
    - Flow
    - Branding
    - Guides

---

Feel free to share more ideas for docs. Also arguments in favour / against restructuring are welcome.

[PaulRBerg]

I agree that the structure of the docs is due for an update.

Just to double-check I understand your proposal. Is this what you meant?

• Top bar
  • Concepts
  • Developer Guides (or maybe just Developers or Development?)
  • APIs
  • Apps

Then:

• Concepts
  • Everything except Protocol Concepts stays the same
  • Rename current Protocol Concepts to Lockup
  • Introduce Flow

If yes, then I have further suggestions:

• Move the Protocol Concepts/ Streaming and Protocol Concepts/NFTs pages upstream, i.e. at the same level with Lockup and Flow
• Move Contracts/Security page to Concepts, at the top-most level

[smol-ninja]

Yes I had similar ideas. Here is the full sitemap: included in the OP.

[PaulRBerg]

I would put:

• Airstreams before Flow
• The Streaming page before Lockup and Flow (and maybe before Use Cases)

But otherwise, it LGTM!

[razgraf]

Looks good! Leaving some notes on the product-side:

Apps

Not sure it makes sense to split in lockup/flow. Would rather apply use-case centric thinking here (as per our own re-org) and go with

• Overview (explains the link between Lockup:Vesting and Flow:Payments)
• Features
  • Vesting
  • Payments
  • Drops
  • General
• Branding

Support

We currently have guides all throughout the docs. Since we now have a new section (cc: @maxdesalle) maybe we can either aggregate or cross-reference these. I'm looking at:

• Support
• Apps / Guides (URL Schemes, CSV Support)
• Contracts / Guides (Snapshot, Etherscan)

Aggregating may not make sense for everything (e.g. does for Apps/Guides moving to Support, but not so much for Contracts/Guides), so at least building a tree of references somewhere in the Support tab would go a long way.

Backwards-compatibility

Given we'll refactor routes please keep in mind to add redirects such that old links don't break when we move to the new nesting structure.

[PaulRBerg]

I agree with the 1st and 3rd proposal, but I don't understand the 2nd. Can you re-explain, please?

[razgraf]

We have "guides" as in pages that act as tutorials in multiple areas.

• https://docs.sablier.com/support/how-to
• https://docs.sablier.com/apps/guides/url-schemes
• https://docs.sablier.com/contracts/v2/guides/etherscan

The first idea would be to aggregate them in a single section. But that's hard, because some are related to code, while others are related to browser-interaction. Nevertheless, they're all "guides" so the second idea was to maybe have a set of links in the "support" page that points to these other guides.

[PaulRBerg]

Oh, got it.

I don't see the benefit of such an aggregation.

Users looking for contract guides will find them after they click on "Contracts", and likewise for "Apps".

[smol-ninja]

This is getting implemented in #186.