Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[host] Add Digital Ocean documentation draft #109

Draft
wants to merge 6 commits into
base: main
Choose a base branch
from

Conversation

muradkhateeb78
Copy link
Contributor

@muradkhateeb78 muradkhateeb78 commented Jan 15, 2024

Add Intial draft documentation for creation of Digital Ocean Cluster and deployment of Ethereal Engine onto it

@heysokam
Copy link
Contributor

heysokam commented Jan 16, 2024

As commented on the Contributing Guidelines in the readme:

  • Bullet points should be marked with - not *
  • Code blocks should always define its language.
    There are a lot of bash language codeblocks in this PR that are not marked as such, and therefore get no syntax highlighting.
  • There are a lot of paragraphs that get bunched together because of not using at the end of lines.
    (end-of-line converts into html <br>)

Markdown syntax rules not commented in the guidelines. Will add them to clarify this:

  • Every < character must be escaped like \<, even inside backticks and code blocks.
    There are multiple cases of this problem, and Docusaurus interprets every .md file as MDX, which means that all instances of <Something> are interpreted as a JSX/TSX component.
    Please change every < into \< to fix the docusaurus compilation issues created by this problem.
  • Please avoid sameline syntax such as: ```some bash command```.
    Those cases should use proper ```bash codeblocks for clarity and readability.
  • Sameline code-blocks should use single backticks, such as `this-is-code` turning into this-is-code
  • Pages should start titles at #, because they become <h1>.
    This PR starts all pages at ## which converts to <h2> and Docusaurus stops listing sub-sections in its right sidebar TOC at <h3>.
    This means the pages in this commit need better titles, as those titles will be the reference used by the user for navigation with the sidebar.
    Frontmatter can be used to specify a title different than its # Title, but as the guidelines mention it should be avoided unless strictly necessary.
  • There is no usage of admonitions in any of the pages.
    ```Note:``` paragraphs should become :::note blocks instead.
    There are other admonition types that could be useful for the article.

Comments on writing style:

  • Some paragraphs are extremely long and hard to follow, when they are giving multiple distinct and separate instructions that could be broken down into more readable paragraphs.
  • There are a lot of sentences with typos with repeated words and overall incorrect grammar. Please do a grammar correction pass before committing to main. Please let me know if you still need help finding them and pointing them out after you do a first correction pass on this.

@heysokam heysokam added documentation Improvements or additions to documentation host Anything related to the Hosting section of the website labels Jan 16, 2024
@heysokam
Copy link
Contributor

heysokam commented Jan 16, 2024

Also, sorry for the early review before the PR was marked as ready.
It has happened a couple of times recently that PRs got merged into main with problems similar to these, so I wanted them documented before a problematic PR gets accidentally merged.

@heysokam heysokam changed the title Add Intial draft documentation for creation of Digital Ocean Cluster … [host] Add Digital Ocean documentation Jan 16, 2024
@heysokam heysokam changed the title [host] Add Digital Ocean documentation [host] Add Digital Ocean documentation draft Jan 16, 2024
@heysokam heysokam mentioned this pull request Jan 16, 2024
11 tasks
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
documentation Improvements or additions to documentation host Anything related to the Hosting section of the website verified-contributor
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants