Technical Documentation

Development ╰ Funding | Staging
3

Where is this hosted? Can I modify it?

I’ll take a look.

I will definitely need some help, but I can start a documentation right away.

It is very important to have it asap in order to be able to onboard new developers.

1 Like
4

cc: @mehowbrainz.

I can contribute to a wallet tutorial section.

2 Likes
5

This is probably a good starting point.
I think it could be re-organized to help new devs get started.

https://wiki.zenon.network/#!index.md

HC1 has discussed requirements to onboard new devs. It’s not a simple problem to solve but good documentation is part of the solution.

6

Imo good documentation solves 80% of the problem.

If you know what’s going on, and some clear instructions & objectives, you have half of the problem solved.

3 Likes
7

Can we migrate the relevant pieces of this to the Zenon Docs page to start consolidating? GitBook docs are a more polished/professional finish

1 Like
8

My recommendation is the following structure:

Technical documentation: I originally thought we could use Intercom to unify Marketing/Sales/Developer support under one platform while onboarding, but I think the ReadMe platform is more robust for developers, so I’m okay to branch it out from Intercom. Intercom themselves even use it for their developer / technical documentation. I like how they have a good UX for API versioning too. Feels more organized compared to Gitbook IMO.

Support documentation: Intercom’s Help Centre product. We got access to a startup program as mentioned here.

We intend to use Intercom in all of the zenon.org funnels and landing pages, with automation/bots/human support by community. Will primarily use Intercom by Marketing, Sales and Support.

I can get both setup as:

Please vote on 2 options for devs/support:

0 voters

If developers.zenon.org replaces the current docs.zenon.org, I will likely create marketing.zenon.org under some platform/tooling (maybe Intercom). The idea will be to organize and host the variety of assets marketing/sales teams could use for campaigning. Or the whole marketing docs could get organized under the attribute.zenon.org family since all marketing tools will be built on that brand.

1 Like
9

I’m concerned about ownership and control of the documentation, as well as cost.

I don’t particularly like the idea of subscribing to and relying on a third-party service to maintain our documentation. Please correct me if I’m wrong about what you’re suggesting, @mehowbrainz.

At this time, I would prefer to keep costs low, decentralize hosting (multiple mirrors), and allow anyone to contribute. Worst case, anyone can fork the repo and maintain their own documentation.

1 Like
10

Gitbook seats aren’t free, ZenonOrg paid for them until this point. Self-hosted solutions still give the control to the infra admin re: database. The forum is an example.

I guess that this vote then applies to whoever wants to contribute to a ZenonOrg hosted technical documentation. I’m fine with whichever option, whether it’s ReadMe or Gitbook, though I’m unsure how to fork Gitbook documentation.

I think regardless of the Pillar opting to provide such a service to the community, the problem of control will exist. The only solution I thought for a future was fragmented ownership of domains (which will require a brand new service/system), or like you mention forks/mirrors.

The ZenonOrg brand believes in a streamlined experience for onboarding newcomers/participants, and hence it proposes ideas which unifies services from a domain, ux, design, branding, flow perspective – with visions to progressively decentralize the trust the community puts into the brand.

1 Like
11

If Gitbook can’t be forked, then the other alternative would be a Github repo for content, but that’s not as friendly UX-wise. Can look for other reliable alternatives.

12

Another platform is Docusaurus, which is a static site generator designed for building documentation websites. It’s typically integrated with version control systems like GitHub, so you could fork the GitHub repository where the Docusaurus site’s files are hosted.

I think @aliencoder’s example uses Docusaurus.

13

I like Docusaurus and mdBook.

They’re 100% free.

2 Likes
14

Seems to be a lot of ways to skin the cat.

Given that @mehowbrainz is driving the majority of this effort coupled with his experience/track record to show for it, I’m happy to defer to what tools he feels most comfortable executing on even if a bit different from poll outcomes.

Let us know where to add all the things.

15

I understand your vision and I know you have good intentions.
I’m not even against any of the solutions you’re proposing, but I think we should initially strive for one that benefits the entire community and minimizes the risk of data loss/gating.

The path of least resistance is forking znn-wiki and maintaining versions that are synced/hosted by multiple community members.

Anyone could take that information, transform it however they wish, and present it in a nicer way.

3 Likes
16

developers.zenon.org repo has been created and the domain has been assigned using Github Pages. Anyone who wants write/maintain permissions DM me your GitHub handle.

@aliencoder would you like to push Docusaurus?

17

The alternative option is to install Docusaurus in this repo. Though we’ll have to wait for admins to review PRs. It depends if we want to go through them, or manage docs ourselves via a new portal like developers.zenon.org ourselves.

18

Please, not another repo that is controlled by Mr Kaine.

I strongly believe that Mr Kaine should only be entitled to control the spork address, to be used as a contingency measure when governance fails.

Everything else, including znnd, can/should/will be managed by the community.

HyperCore One will host a mirror of the documentation, as well.
All participants will need to align on a process to synchronize versions.

3 Likes
19

Whenever ready, I can help theme the site.

1 Like
20

Yes, please.

1 Like
21

A comprehensive documentation is a must!

3 Likes
22

If you fork a repository on GitHub, the standard way to get your contributions incorporated back into the parent repository is through a pull request. Here are the general steps:

  1. Fork the repository: Click the ‘Fork’ button at the top right of the parent repository’s main page. This will create a copy of the repository under your own GitHub account.
  2. Clone the forked repository to your local machine: Open your terminal, navigate to the directory where you want the repository, and use the git clone command with the URL of your forked repository.
  3. Create a new branch: It’s generally a good practice to create a new branch for each set of changes you want to make. You can do this with the command git checkout -b branch-name.
  4. Make changes: Make the changes to the code on your local machine.
  5. Commit the changes: Once you’re satisfied with the changes, commit them using git add . to stage all changes, then git commit -m "Commit message" to commit the changes. Be sure to write a descriptive commit message.
  6. Push the changes: Push the changes to your remote forked repository with the command git push origin branch-name.
  7. Open a pull request: Go to your forked repository on GitHub and click on ‘Pull request’. Choose the branch you just pushed from the ‘compare’ dropdown. Review the changes, then click ‘Create pull request’. Write a descriptive title and comments to help the maintainers of the parent repository understand your changes.

At this point, the maintainers of the parent repository will be able to see your proposed changes. They can review them, discuss potential modifications, and ultimately decide whether to merge your changes into the parent repository.

If the parent repo’s maintainer wants to merge some specific contributions from a forked repo, they can do this manually by checking out the changes in the forked repo, applying them to their own codebase, and then committing that as their own changes. However, this method does not recognize the original contributor in the commit history. Thus, pull requests are a more favorable method as they maintain a clear history of contributions and contributors.

Source: GPT