[Documentation] Have a better documentation and way to update and maintain it regularly

[gaiksaya]

Is your feature request related to a problem? Please describe

This repository contains various aspects of distribution from building to releasing. We have various workflows, images and other components that is used for build, test and release.
However, the documentation is distributed in various places. Example:

• README: https://github.com/opensearch-project/opensearch-build/blob/main/README.md
• Wiki: https://github.com/opensearch-project/opensearch-build/wiki
• Test workflow: https://github.com/opensearch-project/opensearch-build/blob/main/src/test_workflow/README.md
• Release process: https://github.com/opensearch-project/opensearch-build/blob/main/RELEASE_PROCESS_OPENSEARCH.md

As a community user it comes difficult to search for information and get what we are looking for.

Describe the solution you'd like

Move all the content to GitHub wiki. It is great place for "too much" information. The UI automatically lists the sub-topics and makes its easier to parse through the content.
One drawback is, wikis do not allow Pull Requests (yet!). However, there is a work around to automate updating wikis. See https://nimblehq.co/blog/create-github-wiki-pull-request

Describe alternatives you've considered

Keep what is it now.

Additional context

No response

[colossus06]

i think two or more contributor can work together to find a workaround for organizing the documentation to help community better.

[chawinphat]

I would be interested in working on this. If anyone else wants to do it with me, let me know.

[gaiksaya]

Thanks @chawinphat.Assigning this issue to you. Please comment the approaches you would like to move forward with before moving to implementation.
If anyone else is interested in collaborating please comment on this issue.

[SachinSahu431]

Hi @gaiksaya @chawinphat!

The first comment suggested a solution that I tried to implement, but it did not work for me.

As an alternative, I tried using github-wiki-action, and it appears to be working. It involved creating a folder named wiki in root directory and adding a workflow.

Here is the wiki page: https://github.com/SachinSahu431/opensearch-build/wiki

One issue I observed is that linkchecker workflow is failing due to relative URLs.

[chawinphat]

Hi @SachinSahu431 I'll take a look at this over the weekend, and will let you know any progress I make.

[chawinphat]

@gaiksaya @SachinSahu431 I've tried out your method and it looks good to me. I don't think we can use relative addressing since it will point to the .md file instead of the corresponding wiki page?

I have a somewhat working version here.
The only problem is that link checker is failing like you said. The problem is alot less severe if we do not include the main README.md file in our wiki. What are your thoughts?

[SachinSahu431]

Glad to hear it works @chawinphat!

So, by relative address I meant the links in Home.md.

If you check here, I have used the relative address of Welcome-to-Page-2.md file. These relative links on home page will redirect you to the appropriate wiki page.

Hope this will give more clarity:
Go to home page and click on Page 2, you will be redirected to the second page of wiki.

This would avoid manually inserting URLs just like you had to do in your repo here.

[chawinphat]

@SachinSahu431 I talked to @gaiksaya and she said to PR the workflow and get the first page of the wiki up first. I see your point for relative linking inside home.md