Reorganize documentation

[istankovic]

In order to allow easier orientation within our docs, we should reorganize it into meaningful parts and separate the parts intended for different audiences.

Roughly speaking, our audience can be split into several groups:

1. people wanting to provide liquidity and participate in the protocol
2. people wanting to know about Beamer in general
3. potential contributors, looking for ways to help Beamer development
4. security researchers and other people interested in protocol analysis

The focus of the proposed organization has been on splitting the group 1 from the rest.
For one thing, that allows us to better focus the content on catering to group 1, which is
an important factor in boosting the bridge liquidity.

The protocol explainer has been renamed and moved a bit below, together with the explanation
of contracts.

Content intended for contributors/developers has been moved into its own part,
making it clear on the top level and easy to avoid for people who are not part of that group.

Similarly, the intoduction of a new section devoted to reference documentation should
make it easy to find things, whether agent config related or contract-related.

Another new section, Current Deployment, has been proposed to have a central place with all data about the latest deployment.
There's also a new section with audit reports.

Here's what the proposed new structure would look like (please ignore numbers below, they are there only to
facilitate making this illustration):

.
├── 1. Overview
├── 2. The Beamer Protocol
├── 3. Beamer Contracts
│   ├── 1. Architecture
│   ├── 2. Parameters
│   ├── 3. L1 Resolution
│   └── 9. API Reference (links to 7.3)
├── 4. Running an Agent
│   ├── 1. Prerequisites
│   ├── 2. Configuring the Agent
│   ├── 3. Getting the Contract Deployment Information
│   ├── 4. Starting an Agent
│   ├── 5. Stopping an Agent
│   └── 9. Troubleshooting
├── 5. Development
│   ├── 0. Overview
│   ├── 1. Getting Started
│   ├── 2. Agent Architecture and Implementation
│   ├── 3. Making a new Release
│   └── 4. The branching Strategy
├── 7. Reference Documentation
│   ├── 1. beamer Command-line Reference
│   │   ├── 1. beamer agent
│   │   └── 2. beamer health
│   ├── 2. Configuration File Reference
│   │   ├── 1. Agent configuration file
│   │   └── 2. Health-check configuration file
│   └── 3. Contracts API Reference
├── 8. Current Deployment
│   └── contains contracts addresses, possibly also params... all auto-generated
├── 9.0. Audit Reports
├── 9.1. FAQ
└── 9.2. Glossary

[fredo]

Great effort. A couple of comments:

• In the overview we could have a subsection called getting involved whihc links to various places (running an agent, contributing)
• I don't know if I would put running an agent at the very top. If I want to know about a protocol I typically go to the docs. By that time, I don't even know what an agent is good for and what it does. Looks a bit out of context there.

[GabrielBuragev]

Great initiative Ivan!

I agree with @fredo's second point

I don't know if I would put running an agent at the very top. If I want to know about a protocol I typically go to the docs. By that time, I don't even know what an agent is good for and what it does. Looks a bit out of context there.

We could have "The Beamer Protocol" section above "Running an Agent".

---

Suggestions from my side:

• Find a way to include all social media links (twitter, medium, etc.)
• Stats section with reference to Dune queries for the currently deployed contracts

[istankovic]

* In the overview we could have a subsection called `getting involved` whihc links to various places (running an agent, contributing)

Yeah, my thinking was for the overview to looks something like https://docs.python.org/3/ where you could quickly jump to whatever part interests you.

* I don't know if I would put running an agent at the very top. If I want to know about a protocol I typically go to the docs. By that time, I don't even know what an agent is good for and what it does. Looks a bit out of context there.

That is a very good point. I will reshuffle the parts and update the description.

[istankovic]

Thanks for the feedback, I have updated the proposed structure and added the last missing pieces. Let's take this through another round or two of feedback and see if we can proceed.

[bilbeyt]

What do you think about adding mid-term or long-term milestones lets say after Audit Reports? In that part we would list them and update them but not removing but crossing with line. Audience could be 1, 2 or 3 directly, shows the progress.

[istankovic]

What do you think about adding mid-term or long-term milestones lets say after Audit Reports? In that part we would list them and update them but not removing but crossing with line. Audience could be 1, 2 or 3 directly, shows the progress.

I'm not too enthusiastic about it, it's a business matter and can change independently so I'd rather people go elsewhere for that information.