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

Update FairOS documentation #32

Open
11 of 18 tasks
crtahlin opened this issue Dec 2, 2022 · 2 comments
Open
11 of 18 tasks

Update FairOS documentation #32

crtahlin opened this issue Dec 2, 2022 · 2 comments
Assignees
Labels
documentation Improvements or additions to documentation

Comments

@crtahlin
Copy link
Contributor

crtahlin commented Dec 2, 2022

Update FairOS documentation that can be found at https://docs.fairos.fairdatasociety.org/docs/, to be ready before 2022 Winter Solstice event and inline with all the new changes done in connection with FDP.

At one stage, a more thorough review is needed, but going through documentation in a semi-rapid pace, at least the following needs to be done (but more can also be done):

Welcome page: https://docs.fairos.fairdatasociety.org/docs/

  • update info bubble (probably old?)
  • change references to Fairdrive protocol to be about Fair Data Protocol (as it was renamed some time ago; also CTRL-F through other pages for any references)
  • check for broken links (e.g. tutorial section does not exist)
  • check the section menu on the right side of page as it includes some strange text "alt text"
  • it should be mentioned, that this site is about the Go FairOS implementation, while a JS one also exists (fdp-storage)
  • maybe mention that the Go version can be integrated to other languages via some method (WASM?), so the ecosystem is larger then just Go or JS

Introduction : https://docs.fairos.fairdatasociety.org/docs/fairOS-dfs/introduction

  • diagram : Fairdrive connect is now fairos-connect; also maybe some pieces from FDP could be added to diagram where it makes sense?
  • User section: can be updated as we have new kinds of accounts, based on FDP FIP?
  • Pod / Logical Drive section: can be updated with info from the FDP FIP?

Portable account : https://docs.fairos.fairdatasociety.org/docs/fairOS-dfs/portable-account

  • needs content; also link to this section from the Intro page, where we talk about Users

API reference : https://docs.fairos.fairdatasociety.org/docs/fairOS-dfs/api-reference

  • remove the commands from this page, as the are in the linked page with the API reference? do not duplicate work for updating. keep maybe just a simple example, so it is clear how to use the API.

REPL client: https://docs.fairos.fairdatasociety.org/docs/fairOS-dfs/cli-reference

  • check if everything up-to-date
  • could this documentation be generated from code somehow? not to have two places to maintain it (as it is already in the "dfs-cli help" ?) or just keep an example here and how to get to it

Developer info : https://docs.fairos.fairdatasociety.org/docs/fairOS-dfs/developer-info

  • the link to the API gateway points to an old gateway? (or maybe just last major release);
  • also post here or link to somewhere where there is info about versions of FairOS - e.g. the linked gateway runs FairOS 0.7.3-dev; what can a dev expect from that version as compared to latest one

Footer of page

check links, a lot of them do not work

@crtahlin crtahlin transferred this issue from fairDataSociety/fairOS-dfs Dec 2, 2022
@crtahlin crtahlin added the documentation Improvements or additions to documentation label Dec 2, 2022
@tfius
Copy link
Contributor

tfius commented Dec 2, 2022

  • add links to swagger in API documentation

@asabya
Copy link
Collaborator

asabya commented Dec 3, 2022

In the Introduction page we can have a short version for user and pods and direct users to FIPs for a TLDR;

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
Projects
None yet
Development

No branches or pull requests

3 participants