See exonum/exonum#402.

Describe changes in transaction execution brought by exonum/exonum#385.

The Requests article was merged into master in #35, but some questions were left unanswered:

• How do timeouts in requests influence the theoretical properties of the consensus algorithm, given the assumption about the partial synchronicity of the network? (Kudos to @YuryYa for raising the question.)

  • Action item: a note in the requests article once this is figured out.

• How does the processing of messages/states described in Requests corresponds to one described in the consensus spec from #36? Are they interleaved, or is one performed after another, or smth else?

  • Action item: description in the spec and the requests article.

@YuryYa, please feel free to add your suggestions as well.

Use admonitions in the text:

!!! note
    Note contents

instead of

**Notice.** Note contents

[moved here from: exonum/exonum#435]

(Note: I'm a veteran to IT (software & electronics), and a newcomer to the blockchain domain)

This is a collection of issues. It addresses essentially the C-level (as in Cxx like CEO, CTO etc.).

• The product website (exonum.com) is primarily a marketing-instrument
• The website (exonum.com) should prominently mention strengths.
• Category: Exonum is a framework for the creation of private blockchains.
• Strength: Exonum has real-life government-level Success Stories
• Exonum is backed by a commercial entity (bitfury.com)

See, you may think "everyone in the blockchain business domain knows Bitfury". Newcomers do not, and if an evaluator has to fight through the masses of frameworks and tools, he may oversee that a quite impressive company is behind the exonum project.

Support

For me (in the role of an evaluator who has to pick a blockchain-toolset), those are some of the relevant requirements:

• Exonum source-code is available 100% under a liberal open-source-license.
• The project is really open, it encourages contributions from different folks
• Commercial support is available (Question: does bitfury provide commercial support? )
• Missing: a clear pointer to the commercial entity which support the project.

Menu

Current Menu:

EXONUM - FRAMEWORK - USE CASES - PARTNERS - RESOURCES - CONTACT US

• "Framework" could be renamed to "Product"
• "USE CASES" could be renamed to "Quick Start" (Demos should be made available in sourc-code, enabling a very fast project-start.
• "PARTNERS" could be renamed to "SUCCESS STORIES", where exonum shows his real-life success
• RESOURCES could be renamed to "PROJECT", separating clearly the projec-related stuff. Should contain a TEAM submenu
• CONTACT US should contain some basic contact-info (instead of a direct email-link)

Suggested Menu:

EXONUM - PRODUCT - DEMOS - STORIES - PROJECT - CONTACT

alternatively: DEMO = "QUICK STARTS", STORIES =>"SUCCESS STORIES"

It is important that the landing-page shows immediately the most relevant "product classifications" (e.g.: private blockchain), the most impressive success story, and the easiest quick-start (get a system up and running in under an hour, including source-code etc.).

Ideally, the landing-page would mention the commercial backup (Bitfury). An indirect decent way to do so is to mention "Commercial Grade Support" available (which is an absolute plus for an open-source project).

Mockup

All this above can trigger "a discussion till the death". It has sometimes less effort to create a "mockup" and show suggestions than to discuss them. This would be simplified by making the website sources available (see: #163)

@boguslavsky:

• Update theme to mkdocs-material. Task: #28, PR: #33
• SEO meta tags (beautiful posts on Facebook, Twitter, Skype, Slack etc.). PR: #43
• Cryptocurrency step-by-step manual. Task: #37

Could not locate the a project for the exonum.com website. Any plans to provide this, thus contributing becomes easier?

The documentation should support versioning. As an example, see Hyperledger docs.

Ideally, this should work as follows. During documentation build all tagged commits in master a separately builded and represent different versions. Afterwards all versions are combined in the single documentation.

Rewrite information about Consensus from internal wiki to "Architecture -> Consensus" and maybe some others

Apache 2.0 license may be not the best fit for documentation and texts in general; there are specific kinds of licenses for that (e.g., GNU FDL), although more generic Creative Commons licenses are popular as well.

Proposed solution:

• Choose a license for documentation. I'd propose CC BY-SA 4.0 Intl or CC BY-NC-SA 4.0 Intl, but this is a subject of discussion
• Copy the chosen license to the LICENSE file and mention it in README.md
• Move Apache 2.0 license to LICENSE-CODE file and mention in README.md that it concerns code samples in the documentation

cc @djsatok

It's hard to distinguish links in the current theme from normal words. Especially for people with color blindness. Let's use more contrasting color.

message! and encoding_struct! usage in the docs should be updated as per changes in the core. Preliminary search reveals the mentions of the macros in the following articles:

• Serialization
• Service creation tutorial (most probably should be updated corresponding to the code changes in the tutorial)

Related to exonum/exonum#413.

The service interoperability fragment was removed from roadmap in #65. Now it needs to be restored with more details.

Replace storage-related terms like MerkleTable and ListTable, to the terms used in exonum/exonum#166.

CI in the project should be ported from GitLab CI to Travis. This should probably include deployment to the Exonum website (with the help of Travis encryption?).

exonum/exonum@69f5cc3

https://github.com/exonum/exonum-doc/blob/master/src/architecture/configuration.md#sample-configuration-file

replace with link?
https://github.com/exonum/exonum/blob/master/exonum/tests/testdata/config/config02.toml

Clippy and rustfmt blocks are not necessary for installation guide https://exonum.com/doc/get-started/install/ because these items are used for another purpose.

Need to move it to another block of documentation.

Replace current image with attached.

Write subsection "Advanced Topics -> Internal DDoS protection" about DDoS protection from Byzantine validators

In order to provide better user experience, a button/link could be provided to edit pages on GitHub, i.e., one of the links:

• https://github.com/exonum/exonum-doc/edit/master/src/<path-to-md> (edit file)
• https://github.com/exonum/exonum-doc/blob/master/src/<path-to-md> (view file)

The path can be obtained via page.input_path property.

The button can be either place on top of the page (as in Travis docs or MDN), or in the footer.

Things to keep in mind: with #18, it may be necessary to keep several branches of the documentation (rather than tags), as it may be necessary to fix mistakes in the previous versions of the documentation. So it could be necessary to keep the edit button for all versions of the docs, which would lead to the corresponding branch (e.g., .../edit/v0.2/src/<path-to-md>).

• add example of slices serialization
• move Message serialization from the Transactions article

Hi, not found about merkle tree detail doc, can add detail doc about it ?

In my opinion, the document hierarchy can be improved:

• DoS attacks should be removed for now, as agreed previously
• Timeouts adjustment will most probably be removed, too
• License can probably be safely removed too
• Consensus overview may be moved to Architecture section
• Likewise, Serialization can be moved there
• Glossary of terms can be renamed to Glossary and moved to the top as a top-level page (kind of like Home, only after other sections)
• The whole Development section can be flattened
• Cryptocurrency tutorial can be flattened to Create service (the present /intro.md created in #55) and Work with service (if a next part is about light client)
• Similarly, the Services subsection can be flattened. It's probably (still) a controversial point, but I don't think we should try to document all services in the general documentation; instead, they should be well-documented in the respective repos. Config updater and anchoring are a bit special (especially the first one because of its tight coupling to the core), so their documentation may be left here, but we shouldn't try to document every service here - it would be unsustainable.
• I'm on a fence about the Consensus subsection; it can be flattened, but may stay the same.

The proposed hierarchy:

Home
/Get started
  What is Exonum
  Design overview
  Install *
  Create service *
  Work with service -
/Architecture
  Services
  Transactions
  Clients
  Configuration
  Storage *
  Serialization *
  Consensus
/Advanced
  Networking -
  Service testing -
  Configuration updater
  Bitcoin anchoring -
  Merkle index *
  Merkle Patricia index -
  /Consensus
    Specification *
    Requests
    Leader election *
    Timeout adjustment ?
Roadmap *
Contributing *
Glossary

Pages marked with * are in progress, with - are absent.

cc @djsatok

Presently, the documentation is built and verified with the help of CI, but isn't deployed. Naturally, Travis has a variety of options to deploy the built docs (such as deploying it on GitHub Pages). Need to decide on the most fitting one and implement it.

Required for #18.

The article says that the TxTransfer transaction defined in the cryptocurrency service overrides Transaction#info method, which is not true.

As a result of the discussion in #22, some fragments were removed from the Transactions page:

• Transaction templating
• Example for Transaction.execute()
• Censorship resistance

Additionally, there are some topics that were not covered in #22:

• Transaction broadcasting mechanisms
• Differences of transactions in Exonum compared to other blockchains
• Error handling in transactions

At least some (and ideally all) of these fragments should be restored.

Describe on the service page the actual interface of interaction with the Exonum core:

• service_id, service_name
• state_hash (partially described in "Implementation Details" -> "Data Schema"); needs to be more clear
• handle_genesis_block (partially described in "Implementation Details" -> "Configuration")
• handle_commit (almost there; need to add Rust definition)
• tx_from_raw
• public_api_handler, private_api_handler

The current status of the contribution.md states:

If you want to start contributing and not sure where to start, a good frame of reference are open GitHub issues in repositories. Issues are commonly tagged by their relevance, topic and milestone, which should provide some insight into most topical issues relevant to your expertise.

Suggestion

The suggestion is to point potential contributors to a list of trivial issues (this could be a similar tag, but should be the same across exonum projects). The documentation would then be changed to something like this:

"If you want to start contributing and not sure where to start, just look at the trivial issues of the projects. As an example, the exonum trivial open issues. If you are inexperienced with the work-flow, start contributing on the documentation projects."

This way both, experienced and inexperienced developers can find quickly the relevant issues.

In docs (https://exonum.com/doc/architecture/serialization/) explanation about field Payload length is incorrect. At ligth client we can see that it's represent the size of whole transaction (including headers, body and signature). So it's calculated as 74 + body size of tranaction.

Plus, all examples are old, and cannot be used with exonum 0.6

Add meta tags for OpenGraph and Twitter discovery (and also the 'description' meta). Should be straightforward with the meta-data extension for Markdown and a bit of tweaking the mkdocs theme.

Why

Because SEO optimization and ability to paste a link into a Slack channel (or Skype, or Twitter) and get responsive results are good things.

@slowli is there a section created for documenting common explorer api and api of all services? We need to create one if not and consolidate all enptoints' description (which are now 70% documented i believe in exonum-configuration and exonum-btc-anchoring repos). The rest of 30% of explorer api aren't documented so far (corresponding pr hasn't been merged yet).
It would be nice to have one, cross-referenced from other sections of doc.

@defuz @slowli making it one time shot for single occasion only

isn't sustainable approach long term.

Also i really liked the rfc-s idea, to

1. prepare detailed spec for a feature prior to implementation
2. discuss, agree
3. implenent/test/merge
4. update docs

this repo looks like a nice place for rfc-s
too. it would be beneficial for external contributions too.

Update theme to mkdocs-material

Contributor license agreements are used to more precisely define contribution terms for developers. Some examples:

• Apache Foundation
• Eclipse
• JS Foundation
• GitHub

Correspondingly, they could be useful to all public repos in the exonum org.

CLA assistant can be used to setup CLA sign-off for contributors. It comes with a GitHub integration, among other things. Note that there is an option in the assistant to link an entire org to a CLA, which seems to be the preferable way in our case.

Steps forward:

• Test on a test repo, e.g., on @djsatok's example-doc, if that doesn't overburden Alex; alternatively, I can create a test repo myself.
• Create & finalize CLA text. Developer Certificate of Origin (DCO) or Apache's ICLA or SAP's ICLA (comes with the CLA assistant) seem like good starting points
• Expand to this repo and other repos in the exonum org. I'm not sure it's possible while the repos are still private, but we can try.

The leader election doc has been removed from the documentation in #16 because it doesn't quite satisfy quality standards for the documentation. It needs to be restored in a separate PR.

Describe CORS configuration parameters recently introduced in the Exonum core. Should most probably go to the "Architecture / Configuration" article.

Related to exonum/exonum#406.

Hi.
What do you think about an idea to redesign API documentation (or add separate API reference) to make it looks like https://developers.google.com/gmail/api/v1/reference/. Seems that structure like this is more readable and user friendly.