documentation: add an actual README to the project #995
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
iGormilhit
added
the
dev: documentation
mmo
reviewed
May 20, 2020
README.rst
Outdated
| patrons. | ||
|
|
||
| `RERO <https://rero.ch>`__ is a Swiss network of libraries, which is | ||
| under a heavy rebuild process, the |
There was a problem hiding this comment.
Suggested change
| under a heavy rebuild process, the | |
| undergoing a major restructuring, in the framework of the |
README.rst
Outdated
| `RERO <https://rero.ch>`__ is a Swiss network of libraries, which is | ||
| under a heavy rebuild process, the | ||
| `rero21 <https://rero21.ch/en/about/>`__ project. For this project, RERO | ||
| need to replace the old proprietary ILS software that is in use and to redirect |
There was a problem hiding this comment.
Suggested change
| need to replace the old proprietary ILS software that is in use and to redirect | |
| needs to replace the old proprietary ILS software that is in use and to redirect |
README.rst
Outdated
| under a heavy rebuild process, the | ||
| `rero21 <https://rero21.ch/en/about/>`__ project. For this project, RERO | ||
| need to replace the old proprietary ILS software that is in use and to redirect | ||
| it’s effort mainly towards public, school and heritage libraries. Based on it’s |
There was a problem hiding this comment.
Suggested change
| it’s effort mainly towards public, school and heritage libraries. Based on it’s | |
| its effort mainly towards public, school and heritage libraries. Based on its |
README.rst
Outdated
| `rero21 <https://rero21.ch/en/about/>`__ project. For this project, RERO | ||
| need to replace the old proprietary ILS software that is in use and to redirect | ||
| it’s effort mainly towards public, school and heritage libraries. Based on it’s | ||
| 30 years experience in running a library network and all the |
There was a problem hiding this comment.
Suggested change
| 30 years experience in running a library network and all the | |
| 30 years experience running a library network and all the |
README.rst
Outdated
| need to replace the old proprietary ILS software that is in use and to redirect | ||
| it’s effort mainly towards public, school and heritage libraries. Based on it’s | ||
| 30 years experience in running a library network and all the | ||
| scripts that had to be developed around the commercial product, the |
There was a problem hiding this comment.
Suggested change
| scripts that had to be developed around the commercial product, the | |
| scripts and side processes that had to be developed around the commercial product, the |
README.rst
Outdated
| set up a server that harvests the metadata of these ebooks, converts the | ||
| metadata into our data model, and import them into our catalog, attributing | ||
| each ebook to the library that subscribed to the platform. RERO ILS, then, is | ||
| harvesting our ebooks server. |
There was a problem hiding this comment.
Suggested change
| harvesting our ebooks server. | |
| harvests the ebooks server. |
NOTE: It's not quite clear who does what. Is it the ebooks server that imports them into the union catalog, assigning each ebook to the corresponding subscribing libraries? Or is part of this job done by RERO ILS?
There was a problem hiding this comment.
You're right, I've reorganized this part, with the help of your corrections:
RERO ILS customers make use of 3rd-party ebook commercial platforms. A
dedicated server has been set up for harvesting ebook metadata from those
platforms, convert them to RERO ILS's own data model. RERO ILS harvests
our ebooks server, importing the metadata into the union catalog, assigning
each ebook to the corresponding subscribing libraries.
This server is not publicly accessible. The source code is available on GitHub:
`rero-ebooks <https://github.com/rero/rero-ebooks>`_.
You need to prevent your RERO ILS instance to harvest RERO's ebooks server, but
you can run your own ebooks server.
README.rst
Outdated
| each ebook to the library that subscribed to the platform. RERO ILS, then, is | ||
| harvesting our ebooks server. | ||
|
|
||
| But this server is not publicly accessible. The source code is available on |
There was a problem hiding this comment.
Suggested change
| But this server is not publicly accessible. The source code is available on | |
| This server is not publicly accessible. The source code is available on |
README.rst
Outdated
| harvesting our ebooks server. | ||
|
|
||
| But this server is not publicly accessible. The source code is available on | ||
| Github: `rero-ebooks <https://github.com/rero/rero-ebooks>`_. |
There was a problem hiding this comment.
Suggested change
| Github: `rero-ebooks <https://github.com/rero/rero-ebooks>`_. | |
| GitHub: `rero-ebooks <https://github.com/rero/rero-ebooks>`_. |
README.rst
Outdated
| But this server is not publicly accessible. The source code is available on | ||
| Github: `rero-ebooks <https://github.com/rero/rero-ebooks>`_. | ||
|
|
||
| So, you'll either need to prevent your RERO ILS instance to harvest our ebooks |
There was a problem hiding this comment.
Suggested change
| So, you'll either need to prevent your RERO ILS instance to harvest our ebooks | |
| You need to prevent your RERO ILS instance to harvest RERO's ebooks |
README.rst
Outdated
| Github: `rero-ebooks <https://github.com/rero/rero-ebooks>`_. | ||
|
|
||
| So, you'll either need to prevent your RERO ILS instance to harvest our ebooks | ||
| server, or to run your own ebooks server. |
There was a problem hiding this comment.
Suggested change
| server, or to run your own ebooks server. | |
| server, but you can run your own ebooks server. |
BadrAly
approved these changes
May 25, 2020
README.rst
Outdated
| Why RERO ILS? | ||
| ------------- | ||
|
|
||
| `RERO ILS`_ is an ILS by `RERO`_. ILS stands for `Integrated Library Service`_, |
There was a problem hiding this comment.
developed (or brought to you) by RERO?
README.rst
Outdated
|
|
||
| `RERO ILS`_ is an ILS by `RERO`_. ILS stands for `Integrated Library Service`_, | ||
| which can be translated into “a software that helps libraries to do their daily | ||
| tasks”, such as buying documents (books, ebooks, articles, pictures, movies, |
README.rst
Outdated
| its central office) is developing an open source ILS, to be able to address all | ||
| the future needs of its partners and customers. | ||
|
|
||
| Using the same aging commercial ILS and interested by the project for its own |
| research data management. This framework, developed at `CERN`_ is called | ||
| `Invenio`_. | ||
|
|
||
| Who’s going to run RERO ILS, in which context? |
pronguen
reviewed
May 25, 2020
README.rst
Outdated
|
|
||
| Why RERO ILS? |
There was a problem hiding this comment.
I would write "What is RERO ILS", because concretely we give a definition, not reasons.
| and so on. | ||
|
|
||
| Librarians use a *professional interface*, in which they perform their daily | ||
| tasks: |
There was a problem hiding this comment.
I would generalise this list of features, adding etc. at the end of each enumeration and simplifying the enumerations. Otherwise, it will have to be updated after each release.
iGormilhit
commented
May 26, 2020
README.rst
Outdated
Comment on lines
169
to
175
| providing the backend. To work on the frontend of the project, you also need | ||
| `rero-ils-ui`_, which is based on `ng-core`_, MEF, and RERO EBOOKS (see the | ||
| next two section). |
There was a problem hiding this comment.
There's something wrong in this sentence, because actually you don't need MEF and EBOOKS to work on the frontend.
This is the first attempt to write a useful README.rst to the project, not only aimed at developers, but also to the general public and to library managers or professional. I hope it will help people to understand what it is, how to use it and contribute to it. Co-Authored-by: Igor Milhit <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Why are you opening this PR?
Closes #627
How to test?
Read the
README.rstfile.Code review check list