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

docs top-level organisation #202

Closed
ltalirz opened this issue Sep 9, 2021 · 2 comments
Closed

docs top-level organisation #202

ltalirz opened this issue Sep 9, 2021 · 2 comments

Comments

@ltalirz
Copy link
Member

ltalirz commented Sep 9, 2021

This is just recording a first impression of the docs page:

Starting with "deployment" felt a bit strange to me - I would have expected "how to use" first.
On reading through the docs I think I understood the thought process behind the layout a bit better (this follows the standard pattern for a python package: install, how to use, how to develop)... however, many users of the AiiDA lab will actually never install it - they just log in.

For a python package, you typically have roughly two different types of users

  • some users are going to install and use the package
  • some users are going to want to develop the package

Both of these user types have in common that they are likely familiar with python and bash.

For the AiiDAlab, the situation is quite a bit more diverse:

  1. some users are going to log into an existing instance and use the AIiDAlab (may not know any python or bash)
  2. some users are going to want to develop apps
  3. some users may want to run a docker container locally
  4. administrators will want to deploy a multi-user instance
  5. some admins/users will want to develop the AiiDAlab itself

It seems to me that in writing the docs we need to pay particular attention to ensure that the user group 1. is guided well and knows where to look for information.

I'll continue thinking a bit about this, input welcome.

@ltalirz
Copy link
Member Author

ltalirz commented Sep 14, 2021

One possibility would be to organise the docs by the target readership

  1. Users
  2. App developers
  3. Server administrators
  4. AiiDAlab developers

@ltalirz
Copy link
Member Author

ltalirz commented Sep 14, 2021

fixed in e0c9ca1

@ltalirz ltalirz closed this as completed Sep 14, 2021
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

1 participant