SolidOs documentation

[timea-solid]

Observations gathered:

• a person might land on https://github.com/solid maybe from gitter or from the forum or from the website
• it is not clear that SolidOS is the dataBrowser repo that makes use of all the modules (solid-ui, solid-logic) and is the application shown when i get a webId. -> description on the overall repos page is missing under solidOS. (I personally started reading the process repo where Solid OS is not mentioned).
• most information is on SolidOs readme which combines what it is with goals and tech stuff..
• the SolidOs wiki is rather empty
• SolidOs/documentation ->I overlooked it
• solid/userGuide -> it was not clear it is the user guide for solidOS.
  Next I want to start threads about some topics.

1. How to make SolidOs and Data Kitchen the most prominent end user applications repos? Or are there more?
   

2. Should we restructure the SolidOS readme?
   

3. What should be the difference between solidOs readme, documentation and wiki? What should go where?
   

4. How to make the userGuide obvious to the user as the information for the usage of SolidOS?
   

[timea-solid]

Question 1:

• Proposal 1: mention SolidOs and DataKitchen in the process repo readme. (and all the other important repos too)
• Proposal 2: have a description under SolidOs like: "The solid databrowser technology as a web app" (similar to data kitchen)

Question 2:

• Proposal 1: The SolidOS readme should contain a description of what it does and what its goals are and most important a screenshot of how it looks.
• Proposal 2: should contain pointers to other documentation: for devs, for release manager, for user guide (simple users), maybe also to history...

Question 4:

• Mention it in the SolidOs readme -> there should be a section for Users and a section for developers (with links)

[bourgeoa]

I do agree with all your proposals.
A lot of documentation do exist and there must be links cross-referencing them.
Shall that be at the beginning of the README or at the end. I'm not sure that having something only at the end is anygood. An explicit link can be made at the beginning of the README for the most important ones and a general link to MORE DOCUMENTATION for example.

[jeff-zucker]

I think that there is much confusion over the terms SolidOS, mashlib, and databrowser. Here is what makes sense to me - that SolidOS refers to the software tech libraries that power the databrowser and data-kitchen apps and that mashlib be only used to refer to the mashlib library. So we would refer to the app as the SolidOS Databrowser. In terms of the documentation - SolidOS documentation would be about writing and using the software libraries with developers as the audience while Databrowser and Data-Kitchen documentation would be about using the apps with the general public as the audience. So there would be three top documentation roots - SolidOS and SolidOS Databrowser and SolidOS Data-kitchen. The landing pages for each would, close to the start, have a pointer to the others with an explanation of the differences.

In this way of talking about things, we would not have a screenshot of SolidOS, we would have a screenshot of the SolidOS Databrowser. In the explanation of the Databrowser we can say that it is much more than a file explorer, it is an entire operating system backed by the SolidOS tech stack.

[timea-solid]

A bit confusing at first but if properly explained it would make sense.
And where do we put the 'three top documentation roots' ?

[SharonStrats]

Firstly, I agree about having the 3. While I think it was a good change to name it now SolidOS, it has made it confusing a bit as we all begin to switch what we call it. I'm wondering if it would make sense to have documentation in a similar format to the Inrupt one that talks about the sdk libraries or do we want to stick with GitHub readmes like the userguide?

To give some background to anyone reading: Mashlib and Databrowser were the names before last June. But as @jeff-zucker mentioned mashlib is also a library. And databrowser is basically a "compiled" solidOS. Correct me if I'm wrong here.

[bourgeoa]

What should go in a wiki, relative to README and documentation ?

If you already have documentation we could have Q&A referencing solutions to problems or tricks that do not really go into the others ones with links to anything more detailed that could be in documentation, issues .... I find it a good way to find discussions that where opened in issues, even closed issues (else everything is lost).

[timea-solid]

We should not forget about the prominent welcome page: solidcommunity.net webpage information.

[timea-solid]

A diagram of how it currently looks for a user

Can be edited on: https://miro.com/app/board/o9J_lvx4BGo=/

[jeff-zucker]

Thanks for this diagram, it certainly shows that we need to streamline things. My suggestion would be that we define start points for users (the Databrowser and Data-Kitchen user guides) and a single start point for developers (the SolidOS github page). All related pages (e.g. mashlib or solid-ui) should start with a notice pointing to those start pages and describing how the current repo relates to the whole. We can't predetermine where people start, but if we have clear pointers to the top wherever they start, that will help. We can also give a brief overview of the whole SolidOS ecosystem on the sp.org developers page.

In terms of developer documentation, I think the priority needs to be on the auth flow. We are all looking at it and figuring out parts and need to document what we've learned. The next priority, I see as the build process for SolidOS. All of us, I believe, jumped through far too many hoops to build the auth-upgrade branches and I'm sure the difficulty in the process has been a road-block for many who might otherwise have contributed.

In terms of the user documentation, I believe we should first improve the interface and then improve the documention. Things like not having a delete button unless you define yourself as a developer need to be fixed. If you look at #47, you'll see that documenting the current confused interface is much more difficult than documenting a simplified interface. I believe that also applies to some other areas.

P.S. I changed the sp.org developer's page pointer to Data-Kitchen so you can delete that one box that shows jeff-zucker/data-kitchen, that is no longer part of the flow and will be archived. I'll be expanding the README soon and will ask for review when it's ready.

[timea-solid]

The latest version of documentation links:

.

[timea-solid]

Our documentation got some improvements:

• landing page for devs: improved SolidOS Readme (https://github.com/solid/solidos/blob/main/README.md)
• landing page for externals: SolidOS pod contains vision and goals: https://solidos.solidcommunity.net/
• technical know how: docus inside the solidOS repo - https://github.com/solid/solidos/tree/main/documentation
• added some know-how here and there on the according repos (mashlin, solid-logic...)
• diagrams in branches
• blog posts linked on https://solidos.solidcommunity.net/
• dev and team know-how in recorded videos: https://solidos.solidcommunity.net/public/SolidOS%20team%20meetings
  /SolidOS_team_videos.html
• weakly team meetings: https://solidos.solidcommunity.net/public/SolidOS%20team%20meetings/
• team strategy and planning: https://miro.com/app/board/o9J_lkmewLk=/?invite_link_id=858483893759
• improved SolidOS user guide: https://github.com/solid/userguide
• Twitch channel about live coding on solidOS: https://www.twitch.tv/timeaturdean
• https://github.com/solid/solidos/wiki/SolidOS-documentation#technical-style-developers-recommendations

However, we still have problems to overcome in documentation (consider as TODOs):

• documentation on different media is good but it is still very scattered (too many places makes it hard to find and use)
• documentation navigation improvements (one idea is to have it like the MDN documentation)
• userguide needs improvements, versioning maybe, and its own repo with a better name
• video know-how and slides need to be edited and hosted online (not in dropbox, or twitch)
• collect external representations: podcasts, talks
• prototypes needs follow ups, at least blog posts and tutorials to showcase.

[timea-solid]

Update after the GitHub organisation change.

Can be edited on: https://miro.com/app/board/o9J_lvx4BGo=/