comit-network / comit.network Goto Github PK

Recommendation:

1. core-concepts.md - A simple overview of the COMIT core-concepts. Inspire yourself from @da-kami slide (@da-kami to put the link here)
2. glossary.md - A glossary explaining terms, these terms should be used consistently within the documentation. Recommendation is to start with this for consistency purpose as pointed out by @D4nte in https://github.com/coblox/admin/issues/179#issuecomment-575417802. Glossary should be linked to by the rest of the doc.

Decision with Philipp: A glossary as such does not help us in the beginning, rather have sections about e.g. atomic swaps (...) in one document. Similar to here: https://0x.org/docs/core-concepts#introduction

At a later point we can take more time and split it up into several files, explaining details. For now I would have one markdown file explaining COMIT.

Graphical content helps. We have to see how we achieve this, maybe we literally embed a certain slide-set from google-presentation...?

Keep in mind: This is not an RFC! Don't describe things too scientific, create a user documentation rather than a paper 😉

Note: Talk to @D4nte as he has few examples in mind.

Problem

It'd be nice to have graphs in the documentation such as:

• Network graph for start-env in the Getting Started section #10

However, plantuml does not allow to do "pretty" graph and it can be quite a time sink.

Goal

Clear documentation and professional looking graphs.

Recommendation

A current position for a product designer is open, is that something that could be part of his role?

Problem

Currently, the SDK doc included in the website is the one coming from comit-js-sdk master branch.
This is an issue because a developer may purposefully use an older (or released) version of the sdk. In this case, they currently cannot access the SDK doc from the website.

Goal

Support versioning of documentation on the website. So that the user can select the version of SDK he is viewing.
The version as per the git tags/npm packages.

The aim of this issue is to decide on the website structure to hold several versions and how to select such versions (dropdown, etc). Probably need to generate the doc for a couple of the latest versions of the SDK to validate the look and feel.

Note: Decide to default to master or latest release (can be decided in #29).
Note: Do not automate at this stage, automation is handled in #29.

Problem

The html documentation generated by typedoc is more visual than the markdown version. However, there's really no great way to port the HTML version other than to host it as a standalone domain, which makes referencing and linking to it from the handwritten tutorials more finicky.

Fortunately, having it as Markdown gives us a lot more control on how we render it on the website. It can definitely be presented better by using proper CSS, tables, and other visual elements.

Solution

One solution is to use custom CSS and apply it across both handwritten and autogenerated documentation with a custom Docusaurus theme.

Having a custom theme gives a structure that we can use to properly style API docs, making more readable and consistent with the style of the agency work on the static site.

Problem

When navigating to /docs on the homepage there is nothing there. (no page, 404)

Goal

Not have 404 but an entry point to the documentation.

Recommendation

Redirect to https://comit.network/docs/getting-started/create-comit-app/

Consider a generic solution that would allow to fix this issue for any url and redirect to the best existing page.
Example: https://comit.network/docs/getting-started/-> https://comit.network/docs/getting-started/create-comit-app

Right now the comit.network site is hosted under the TenX org. It's cheaper with just 2 members, but adding more members needs is a big hassle and goes through a lot of people.

Moving forward, we should sign up to our own Netlify Pro account https://www.netlify.com/pricing/ for easier collaboration.

Problem

When opening the comit.network documentation on a mobile device the embedded google presentations break the design.

Example:

Goal

Make the documentation usable on mobile devices.

Recommendation

1. Hide the slides on mobile and just give a link.

2. Since integrating the presentation slides is a great feature I would say we keep that.
   That means we have to improve the iframe embedding. I played around with this a bit.

Quick fix:

Change all the iframe width tags to 100% instead of the fixed width.
This will scales the width properly in Docusaurus, but keeping the height fixed sometimes is not optimal (but at least does not break the design).

Screenshots:

I also tried making the height dynamic, but that causes problem (like the presentation being tiny).
Keeping the height

If you want to do more than the quick fix:

You can also investigate more and play with CSS. See: https://stackoverflow.com/questions/325273/make-iframe-to-fit-100-of-containers-remaining-height (more research might be required.)
But that will require more testing so we don't break Docusaurus lay-outing.
There is also the viewport and meta tag (HTML 5, https://www.w3schools.com/css/css_rwd_viewport.asp) that should be usable for such kind of problems, but I had trouble using it with Docusaurus (error or completely white page when integrating it).

Problem

The link https://comit.network/docs/comit-sdk doesn't work, one has to append /index for it to work.

/index should be implied.

Goal

Nice links without unnecessary clutter.

Problem

There is no clear explanation of what is the infrastructure needed to run COMIT once a developer is ready to go on testnet or mainnet.

Goal

Ensure that users and developers are aware of what is needed to run COMIT on testnet or mainnet.

Recommendation

A documentation that explains the different interactions between the components (cnd, blockchain nodes, wallets).

Release v2.0.0-alpha.41 was just released and we should upgrade to this to resolve #9 since my feature request facebook/docusaurus#2253 has been merged.

How to build your own app tutorial, resulting to the separate apps example.

This tutorial is about CODING and getting started with the code. It is more than a mere "getting started" section that shows ho to use a tool.

The goal of the tutorial is to make a developer actually code the preferred Hello World example: examples/btc_eth.

Note:

• There is a placeholder file: tutorials/write-a-comit-app.md.
• Include the manipulation of the SwapDetails object (to know the status, check txid, etc) in the tutorial.

If you to https://comit.network/docs/getting-started/create-comit-app/ and click the logo, it does not go to the homepage because the Docusaurus navbar uses client-side navigation.

The static .html site may need to be embedded to a docs/pages/index.js similar to https://github.com/comit-network/comit.network/tree/b9ff4644f211bf897c3815e9608cdb3aa1a489cb/src/pages

This issue tracks any known issue with autogenerated SDK docs.

1. Typedoc generates duplicates, unnecessary elements

The consts value is duplicated: https://deploy-preview-22--comit-network.netlify.com/docs/comit-sdk/modules/_negotiation_order_

Const BITCOIN_DECIMALS

• BITCOIN_DECIMALS: 8 = 8

2. Underscores in URLs stripped during browser navigation

Example: https://deploy-preview-22--comit-network.netlify.com/docs/comit-sdk/modules/_negotiation_order_

We should stop Typedoc from generating underscores in URLs as they are stripped away by the browser.

Decisions to make:

• When and how should Docusaurus be triggered to deploy a new version of the homepage (including documentation)
  • I don't have a clear solution on that in my head yet. the build pipeline(s) may be a result of this.

Proposal:

We will have to distinguish scenarios where we release a new homepage version upon changing hand-written documentation or generated documentation. For hand written documentation there will be a PR (created after changing/adding files).

The documentation for the comit-js-sdk should be generated and released upon release a new SDK version. The SDK release process should automatically trigger the creation of a PR in the documentation repository. This https://github.com/coblox/admin/issues/182#issuecomment-575003774 by @yosriady adds some more details on how to achieve the integration and release of generated documentation parts.

The webpage (including the documentation) is released upon merging a PR.

Problem

It is not clear from a third party developer point of view what sections he should start with.

The current structure:

Getting Started <- Relevant for app dev
	Create-comit-app <- This is actually about running a demo
COMIT Protocol <- More details for crypto experts
Core Concepts <- General details for curious
COMIT Javascript SDK <- Relevant for app dev

Goal

Guide app dev through the documentation

Recommendation

Getting Started
	Run an example <- was Create-comit-app
COMIT Javascript SDK <- Re-ordered
COMIT Protocol
	Core Concepts <- Move under COMIT Protocol section

Closes #7

Right now, the build process is not yet automated. Ideally, Github will trigger the npm run build:sdk command whenever there is a new release of the comit-js-sdk repo and update the website.

Build Workflow

In the meantime, if you need to update the API docs, here's how you can do it.

.
├──work/
|   ├── comit-js-sdk/
|   └── comit.network/

• First, make sure that you have both comit-js-sdk and comit.network repos on your machine, within the same directory (see above.)
• Do a git pull to make sure both repos are up-to-date.
• cd comit.network/ and run npm run build:sdk. This will generate comit-js-sdk documentation and update the website source in a single step.
• Open the website locally with npm run start to make sure there are no syntax errors.
• git add . git commit to commit the updated source files.
• git push to master rebuild the live website.

Workflow Definition

• The above steps can be defined as a Github action which is triggered whenever a new SDK release is created.

• When the action is triggered the workflow should Open a new PR containing the commit.

• The workflow should live in the comit.network repo, and be triggered by a release event from the comit-js-sdk repo. The workflow will git clone comit-js-sdk and run the npm run build:sdk command.

Note: You can use the repo_dispatch github feature, see how it is done in coblox/admin for the label sync.
Note: OR you can do the git commit and push on comit.network from comit-js-sdk github action.
Note: Be aware of release automation for SDK #181

Reported by Franck:

Do we have something to track that the COMIT SDK logo does not look good in night mode ? https://deploy-preview-22--comit-network.netlify.com/docs/comit-sdk/index

Problem

There is no clear explanation of what comit-scripts does.

Goal

Ensure that users and developers are aware of what they need to run and what comit-scripts does for them. It should be clear that they do not need to start their own nodes or worry about funding. It should also be clear on how comit-scripts forward information to the apps (via the env file).

Reasoning why some decision were made would also be interesting to allow the dev to better grasp the point of this tool.

Recommendation

A documentation that explains what comit-scripts gives you and how a developer is expected to interact with it, and what it does not give you (testnet/mainnet).

Should go under the Getting Started section.

@yosriady please feel free to add to this if there already is something on your radar.

Note: This ticket is also a reminder that the documentation does not just stop at the current tickets we have, but should be constantly maintained.
I put several questions at the bottom.

Problem

I was just going through the product-squad wiki and noticed this comment at the end:
( ref: https://github.com/coblox/product-squad/wiki/COMIT-Product-Technical-Specification#feedback)

In particular:
* An explanation of the Order message schema.
* An explanation of the steps of the COMIT protocol.

This is only partly done in the current documentation and should be extended.

Goal

A more useful and elaborate documentation.

Proposed Solution

Immediate actions:

• Extend the "COMIT Protocol" Section (or should this be somewhere else?
  • Add a graphic that explains the relation between cnd <> comit-js-sdk <> create-comit-app. Include taker and maker as actors so it is clear what the different tools bring to the table.

Clarification needed:

• Documentation for Order (or Negotiation in total...)
  • Should we actually have an example for the Order message schema?
  • The whole negotiation is basically still in the a trial/example state. Are we planning to change this at some point?
  • Is more documentation needed at the moment?

Mention this besides code related updates:

• upcoming community coffee on 07.05.
  • jitsi link: https://meet.jit.si/COMIT-Community-Coffee-05-2020
  • google calendar event link: https://calendar.google.com/event?action=TEMPLATE&tmeid=NHEzb2tkNDJtcXFzdnNyNG9oM2UzNGhpc3MgdGVueC50ZWNoX202dWp2OXQ4cGluajAxYmI2NXV0aHRmcnM0QGc&tmsrc=tenx.tech_m6ujv9t8pinj01bb65uthtfrs4%40group.calendar.google.com

Markdown file that explains shortly what create-comit-app is about and how to use it.

This ticket describes a "getting started" section for RUNNING create-comit-app with our preferred Hello World example. This should be very simple. It CAN include an https://asciinema.org/ video (but does not have to).

What we call examples/btc_eth is our preferred Hello World example. Thus we focus the "getting-started" section on that.

A more detailed coding example is described by coblox/admin#178

Problem

As highlighted by @yosriady in #42 (comment). A developer will go through the documentation is the way we present it to them and/or the way they feel they need to know.

Currently, we have a vague idea of this journey but it not explicitly stated.

Goal

The goal is to explicitly state the journey so that:

• We can review and validate it and confirm it makes sense
• Ensure that what we do is aligned with the target journey
• Better guide a developer so they know when they need to expect such and such information, allowing them to skip forward if they want to

Recommendation

Ensure that the left sidebar matches the journey even if it means having some empty sections for now.

Journey proposal

Can be discussed as part of the review process.

1. Arrives at the start-page of comit.network
2. Read about what COMIT does (short overview)
3. Read Getting Started section to run an example.
4. Read create own app Tutorial
5. Sets up with comit-scripts (Developers have no knowledge of infra just yet). A general overview would be helpful here, but perhaps it makes more sense later on.
6. Read Core Concepts and Protocol explanation
7. Finished going through create own app tutorial
8. Developer is now ready to deploy their COMIT app on testnet.
9. Infra Overview would be most useful here, when deploying the app as want devto stop using comit-scripts. So maybe time to explain what comit-scripts does it details at a way to explain what is needed.
   1.Developer has gone live with the COMIT App on testnet / mainnet

Sections

    Getting Started
        Run an example app # Current `create-comit-app` get started
        Dev Environment Setup # Short overview of comit-scripts
        Write your first app
        Deploy in testnet # infrastructure overview + what needs to happen to go testnet
    COMIT Protocol
        COMIT protocol stack
        COMIT projects
        Core Concepts
            Atomic Swaps using HTLCs
            (...)
    COMIT JavaScript SDK

Actions to take

• Rename "Create-comit-app to "Run an example app"
• Pull comit-scripts setup description out of the current "Create-comit-app" section into "Dev Environment Setup".
• Move "Core Concepts" under "COMIT Protocol"
• Rename "Javascript" to "JavaScript"

Move the current comit.network to serve as start-page of Docusaurus.
Add Link to Documentation.

At the moment blog.coblox.tech is just not reachable any more.
Once the new start page is launched we can re-evaluate a proper redirect.

The generation tool of choice is Typedoc, it uses the README as the home page so we can update the README for this issue.

Problem

We want the URL of the old blog (https://blog.coblox.tech) to redirect users to the new one (https://comit.network/blog).

Ideally, we want to redirect https://blog.coblox.tech/2020/01/31/january-dev-update.html to https://comit.network/blog/2020/01/31/january-dev-update. However, this is actually impossible with pure DNS because DNS has no knowledge of HTTP paths.

Solution 1

If possible, add a 301 URL Redirect record from blog.coblox.tech to comit.network/blog on the DNS dashboard.

Solution 2

If the dashboard doesn't provide the 301 Redirect rule, we'll need to do this approach to achieve the same thing (except the rest of the URL paths are removed.)

It's a complicated multi-step process, summarized here:

• In the Route 53 console, make sure the hosted zone named blog.coblox.tech exists.
• In S3, create an empty bucket blog.coblox.tech
• Select the bucket you just created, and then choose Properties. Expand the Static Website Hosting drop-down menu, and then choose Redirect all requests to another host name.
• In the Redirect all requests to another host name field, enter comit.network/blog and save.
• In the Route 53 console, select the hosted zone named blog.coblox.tech
• In Route53, create an A record for blog.coblox.tech with the following values:

Record Type: Choose A – IPv4 address.
Alias: Choose Yes.
Alias Target: Select the blank value field, expand the drop-down menu, and then choose your S3 bucket `blog.coblox.tech` under the heading S3 Website Endpoints.
Routing Policy: Choose Simple.
Evaluate Health Target: Choose No, and then choose Create.

Make sure that the alias target above is set to the blog.coblox.tech bucket

You can confirm it works by browsing to blog.coblox.tech or CURL to blog.coblox.tech. You should see "301 Moved Permanently" in your curl output, redirecting to comit.network/blog.