dtr-org / docs.unit-e.io Goto Github PK

Describe the high level technical concepts which are necessary to understand how unit-e works.

Quite a bit of material can be imported from the bitcoin.org developer guide as a base and then be adapted to unit-e.

These are the topics which are covered there:

• Block chain
• Transactions
• Contracts
• Wallets
• Payment processing
• Operating modes
• P2P network

We have an initial import with names adapted to Unit-e in the doc-prototype wip branch but without any further adaptions of the content.

Describe the important terms which are used in the context of Unit-e in a glossary. This would be extremely helpful as a reference for all kind of other documentation so readers have a way to look up terms used in other places. Terms can be hyper-linked from other parts of the documentation.

The glossary should cover basic general terms such as "Blockchain", "Transactions", "Address" which also are used in Bitcoin as well as Unit-e specific terms such as "Proof of Stake", "Finalization", "Remote staking", etc.

Some material which might be useful as a base:

• bitcoin.org vocabulary
• bitcoin.org developer glossary

We have an initial import with names adapted to Unit-e in the doc-prototype wip branch but without any further adaptions of the content.

Document how to run a unit-e node. This is targeted at operators. It should cover general instructions how to run a node in different modes and also cover the specific aspects of running proposer or validator nodes. Another important aspect is security and availability considerations.

The desktop wallet is targeted at end users which want to make use of Unit-e. We need some end user manual which describes how to use it. This should also cover security considerations, in particular how to keep keys safe.

• Create README
• Document how to run and test the project
• Check that license is stated clearly
  • License note in README
  • License file in root directory
  • Add license headers to all source files. Can be done with
    copyright_header.py).
    Run copyright_header.py insert <filename> to add headers and
    copyright_header.py report <directory> to check the repository for headers
• Copy code of conduct from unit-e repo
• Create a CONTRIBUTING.md. This should refer to the unit-e CONTRIBUTING.md
  because that contains detailed instructions about the general process but
  point out any special considerations for the new repo.
• Templates
  • Take
    .github/ISSUE_TEMPLATES
    from unit-e and adapt
  • Take
    .github/PULL_REQUEST_TEMPLATE.md
    from unit-e and adapt
• Repository settings (needs admin access)
  • Disable merging and rebasing pull request on merge
  • Set up master as protected branch which requires review on pull
    requests and requires status checks to pass, including administrators
  • Enable Mergeable app (add
    configuration)
  • Enable DCO app

We have a spec in the unit-e-docs repository which contains a description of how block proposal and finalization work. We should incorporate this into the documentation in the docs.unit-e.io repository. The document also contains a glossary. This should be incorporated into the glossary of the docs repository (#8).

We need reference documentation for the peer-to-peer protocol. This is important for people who want to understand how Unit-e works in detail as well as developers who want to work on unit-e or other software which needs to deal with the protocol.

Maybe there it would be good to generate this documentation from information maintained as part of the unit-e source code so that it's naturally maintained and kept up to date and correct.

The bitcoin.org P2P Network documentation might be helpful as a base.

We have an initial import with names adapted to Unit-e in the doc-prototype wip branch but without any further adaptions of the content.

Much of the architecture and underlying technical concepts are specified and discussed in the form of improvement proposals. There are Unit-e improvement proposals (UIPs) which directly contain technical specification for unit-e. We should reference them from the documentation.

There also are the Bitcoin Improvement Proposals (BIPs) which describe the upstream specification. We inherent some of them. It would be good to find a way how to reference the ones which are relevant to unit-e.

To make sure the language of the documentation is clear and correct we should get some proof-reading by a native speaker. This is especially important at the beginning after new material has been created. It can be repeated once in a while to keep the quality of the language high.

Just as with the program code we should also act as good citizens of the open source community with the documentation. We should contribute back to the upstream documentation, especially where it's also relevant to us, and where we refer to or use the upstream documentation as a base.

By working upstream we can tap into the expertise of the larger community and contribute our part to maintaining a healthy overall ecosystem.

Some examples for contributing upstream:

• Fixing small issues such as typos and formatting we see in the upstream documentation while we work with it.
• Content we improve or write which also applies to Bitcoin.
• Documentation infrastructure such as the automated generation of RPC docs.

We have reference documentation for all RPC calls of unit-e. We still need some introduction which explains the basic concepts of the RPC interface, how data is represented, how authentication works, etc.

The intro to the Bitcoin Core API might be useful as a base.

There are research papers about the concepts implemented in unit-e. They should
be referenced from the documentation.

The docs need to be styled so that it's easy to read, use, and navigate them and they look good. The styling should be consistent with the Unit-e web site (which is still work in progress).