Commit bf674642 authored by Jurriaan H. Spaaks's avatar Jurriaan H. Spaaks
Browse files

updated documentation

parent d5e2cb11
......@@ -24,5 +24,6 @@
"replacementPatterns": [{
"pattern": "^/",
"replacement": "https://github.com/research-software-directory/research-software-directory/blob/master/"
}]
}],
"retryOn429": true
}
......@@ -60,17 +60,20 @@ To quickly get a running Research Software Directory up and running on your loca
```
Go to [http://localhost](http://localhost) (disregard certificate warning) to see the Research Software Directory
website. You should be able to see all non-authenticated pages, but editing data or harvesting data from external
sources won't work. To bring up the website with all bells and whistles, read on in the next chapters.
## Use cases
1. [Contributing](/.github/CONTRIBUTING.md)
1. [Running an instance with your own data sources](/docs/configure.md)
1. [Entering your own data](/docs/instruction/README.md)
1. [Changing the look and feel](/docs/customize.md)
1. [Finding your way: Research Software Directory services](/docs/services.md)
1. [Documentation for developers](/docs/dev.md)
1. [Documentation for maintainers](/docs/maintaining.md)
1. [Hosting your instance online](/docs/hosting.md)
1. [Running an instance of the Research Software Directory in production](/docs/production.md)
1. [Security concerns](/docs/security.md)
sources won't work. To bring up the website with all bells and whistles, refer to selected resources from the list
below.
## Further resources
<!-- see also docs/README.md -->
1. [Entering data about your software in an existing instance](./docs/entering-data.md)
1. [Configuring your instance to use your own data sources](./docs/configuring-your-instance-to-use-your-own-data-sources.md)
1. [Changing the look and feel](./docs/changing-the-look-and-feel.md)
1. [Hosting your instance online](./docs/hosting.md)
1. [Running an instance of the Research Software Directory in production](./docs/production.md)
1. [Finding your way: Research Software Directory services](./docs/services-overview.md)
1. [Documentation for developers](./docs/documentation-for-developers.md)
1. [Documentation for maintainers](./docs/documentation-for-maintainers.md)
1. [Security concerns](./docs/security.md)
1. [Contributing](./.github/CONTRIBUTING.md)
# Contents
<!-- see also bottom of main readme -->
1. [Entering data about your software in an existing instance](./docs/entering-data.md)
1. [Configuring your instance to use your own data sources](./docs/configuring-your-instance-to-use-your-own-data-sources.md)
1. [Changing the look and feel](./docs/changing-the-look-and-feel.md)
1. [Hosting your instance online](./docs/hosting.md)
1. [Running an instance of the Research Software Directory in production](./docs/production.md)
1. [Finding your way: Research Software Directory services](./docs/services-overview.md)
1. [Documentation for developers](./docs/documentation-for-developers.md)
1. [Documentation for maintainers](./docs/documentation-for-maintainers.md)
1. [Security concerns](./docs/security.md)
1. [Contributing](./.github/CONTRIBUTING.md)
# What is the Research Software Directory?
Here is an example of what a product page may look like:
![/docs/images/20180627-webcapture-xenon.png](/docs/images/20180627-webcapture-xenon.png)
While the content
shown on the product page can be completely customized, by default it includes a
_Mentions_ section, which can be used to characterize the context in which the
software exists. The context may include links to scientific papers, but is
certainly broader than that: for example, there may be links to web applications
that demonstrate the use of the software, there may be links to videos on
YouTube, tutorials on readthedocs.io or Jupyter notebooks, or there may be links
to blog posts; really, anything that helps visitors decide if the software could
be useful for them.
The Research Software Directory improves findability of software packages,
partly because it provides metadata that helps search engines understand what
the software is about, but more importantly because of the human centered text
snippets that must be provided for each software package. After all, discovery
of a software package is often not so much about finding it but knowing that you
found it.
# Configuring the Research Software Directory
# Using your own data sources
The research software directory is configured using a file with environment
variables called `.env`. An example config file
......
......@@ -12,7 +12,7 @@ git clone https://github.com/<your-github-organization>/research-software-direct
## Try it out, step 2/3: Configure
See [configure.md](configure.md)
See section [Using your own data sources](using-your-own-data-sources.md).
## Try it out, step 3/3: Start the complete stack using [docker-compose](https://docs.docker.com/compose/)
......
......@@ -42,7 +42,7 @@ selecting them via the dropdown list in the Admin interface of the Research Soft
### Output and impact
The items on the dropdown list are harvested periodically from the
The items on the dropdown list are harvested periodically from the
[Netherlands eScience Center group on
Zotero](https://www.zotero.org/groups/1689348). For reference, Zotero is the
place where we keep track of NLeSC's _output_ and _impact_:
......@@ -107,6 +107,8 @@ blue ``+`` symbol.
1. Optionally, fill in the person's email address
1. Optionally, provide an image of the person
1. **Don't forget** to click ``Save`` when you're done.
1. Refer to section [_Delays_](#delays) and section [_The query
trick_](#the-query-trick) to know when you get to see your changes.
## How do I add a new ``Mention``?
......@@ -128,6 +130,8 @@ blue ``+`` symbol.
produced with NLeSC funding), or as "impact" (the mention was produced without
NLeSC funding, for example when a paper cites code that NLeSC created).
1. **Don't forget** to click ``Save`` when you're done.
1. Refer to section [_Delays_](#delays) and section [_The query
trick_](#the-query-trick) to know when you get to see your changes.
## How do I add a new ``Organization``?
......@@ -143,7 +147,8 @@ clicking the blue ``+`` symbol.
1. Organizations often offer the source files for their logos via a link on
their website, usually named something like "Press" or "House style".
1. **Don't forget** to click ``Save`` when you're done.
1. You may need to refresh the page to see newly added items appear in the left pane
1. Refer to section [_Delays_](#delays) and section [_The query
trick_](#the-query-trick) to know when you get to see your changes.
## How/when do I get to see my changes?
......@@ -161,12 +166,12 @@ If your change only involves the Research Software Directory's Admin interface,
for example when you add a pre-existing ``Mention`` to a ``Software`` and press
``Save``, the corresponding database collection is updated immediately but the
data needed for populating the product page template is collected at intervals.
Again, refer to the schedule at
Refer to the schedule at
[https://research-software.nl/schedule](https://research-software.nl/schedule) and look for the
``python app.py resolve`` task.
If your change involves an external data source, e.g. you have new commits on
GitHub, or a new release on Zenodo, you will only see the resulting data show up
GitHub, a new release on Zenodo, or you've added an entry to Zotero, you will only see the resulting data show up
in the Research Software Directory after the corresponding data is harvested.
Check [https://research-software.nl/schedule](https://research-software.nl/schedule) and look for
the ``python app.py harvest commits`` and ``python app.py harvest citations``
......
This diff is collapsed.
# Projects
Since the projects in Zotero are not searchable, find your project below:
| Code | Title | Reponsible for end report content |
| ----------- | -------------------------------------------------------------| ----------------------------------- |
| 650001005 | Self Organizing Archives |
| 650001003 | Online Groups in organizations |
| 650001002 | Expotree |
| 33017002 | Genetics of sleep patterns | Vincent
| 33016009 | MAGIC | Niels
| 33016008 | Visualizing Uncertainty and Perspective Plus | Maarten
| 33016007 | VLPB-AVE2 | Lars
| 33016006 | Blue-Action | Yang
| 33016005 | TWEX Translating weather Extremes into the future | Gijs
| 33016004 | Bird Avoidance System (BirdRadar) | Jurriaan
| 33016003 | UCL: Classifying activity types | Dafne
| 33016002 | The Riddle of Litery Quality | Carlos
| 33016001 | Commit / valorisation call 2015-2016 | Romulo
| 33015004 | ANDI-Advanced Neuropsychological Diagnostics Infrastructure | Janneke
| 33015003 | IndoDutch - Understanding Large Scale Human Mobility | Berend
| 33015002 | Primavera | Rena
| 33015001 | From sentiment to emotions - Embodied emotions | Janneke
| 33013002 | LifeWatch | Christiaan
| 33013001 | Flysafe 2 | Jurriaan
| 27017G06 | NEWSGAC:Advancing Media History by genre classification | Erik
| 27017G05 | EviDENce: Ego Documents Events ModelliNg | Martine
| 27017G04 | TICCLAT:Text-Induced Corpus Correction and Lexical Assessmen | Valentina
| 27017G03 | Bridging the gap: Dig. Humanities the Arabic-Islamic corpus | Patrick
| 27016S06 | Autograph: Automated multi-scale Graph maipulation | Rena
| 27016S05 | City Cloud: From the things to the cloud and back | Hanno
| 27016S04 | High Spatial Resolution phenological modelling | Romulo
| 27016S03 | Software Analytics of the global impact of escience software | Atze
| 27016P09 | 3D printing of human body parts | Adrienne
| 27016P07 | Data-mining tools for abrupt climate change | Johan
| 27016P06 | Automated analysis of online behaviour on social media | Erik
| 27016P05 | Case Law Analytics | Dafne
| 27016P04 | Parallelisation of multi point-cloud registration | Ben
| 27016P03 | Data quality in a distributed learning environment | Berend
| 27016P02 | Towards a species-by-species approach to global biodiversity | Jason
| 27016P01 | Fast open source simulator of low-energy scattering | Johan
| 27016G08 | Visual Storytelling of Big Imaging Data | Maarten
| 27016G07 | Accelerating Astronomical Applications 2 (Triple-A 2) | Atze
| 27016G06 | A methodology and ecosystem for many-core programming | Alessio0
| 27016G05 | DIRAC: Distributed Radio Astronomical Computing | Hanno
| 27016G04 | DeepRank: Scoring 3D protein | Sonja
| 27016G03 | Googling the cancer genome | Arnold
| 27016G02 | Emotion Recognition in Dementia | Vincent
| 27016G01 | eEcoLiDAR | Yifat
| 27015S01 | Error Detection and Localization for Radio Telescope SHM | Hanno
| 27015G09 | AA-ALERT | Ronald
| 27015G08 | iDark: The intelligent Dark Matter Survey | Faruk
| 27015G07 | Automated Parallel Calculation of Collaborative Stat Models | Patrick
| 27015G06 | Enhancing protein-drug binding prediction | Lourens
| 27015G05 | DynaSlum:Data Driven Modeling and Decision Support for Slums | Elena
| 27015G04 | What Works When for Whom? | Janneke
| 27015G03 | Towards Large-Scale Cloud-Resolving Climate Simulations | Gijs
| 27015G02 | Algorithmic Geo-visualization: from Theory to Practice | Carlos
| 27015G01 | e-MUSC - Enhancing Multiscale Computing | Lourens
| 27015911 | Real-time detection of neutrinos from the distant Universe | Ben
| 27015910 | Improving Open-Source Photogrammetric Workflows | Elena
| 27015602 | Diagnosis of active epilepsy in resource-poor setting | Vincent
| 27015601 | Enabling Dynamic Services | Niels
| 27015001 | Detecting anomalous behaviour in the Amsterdam Arena | Sonja
| 27014909 | Mining Shifting Concepts through time (ShiCo) | Carlos
| 27014908 | Giving pandas a ROOT to chew on | Jason
| 27014907 | Compressing the sky | Vincent
| 27014906 | Massive Biological Data Clustering | Sonja
| 27014905 | RT-SAR | Hanno
| 27014904 | Large Scale Data Assimilation-eWatercycle | Niels
| 27014903 | DiLiPaD | Janneke
| 27014901 | Platform for Chemical Data Analytics | Stefan
| 27014503 | Recording history in large news streams | Stefan
| 27014502 | Achieving Multidisciplinary High-Throughput | Elena
| 27014501 | A Lightpath for Optical Coherence Tomography imaging | Elena
| 27014402 | Visualising uncertainty and perspectives | Maarten
| 27014401 | DIVE+ | Carlos
| 27014204 | Prediction of Candidate genes for Traits | Arnold
| 27014203 | ERA-URBAN | Ronald
| 27014202 | Computational chemistry made easy | Lars
| 27014201 | 3D-e-Chem | Stefan
| 27013902 | Texcavator | Janneke
| 27013901 | Mapping the Via Appia in 3D | Romulo
| 27013805 | PIDIMEHS | Patrick
| 27013804 | HADRIANVS | Patrick
| 27013803 | Beyond the book | Carlos
| 27013802 | From sentiment to emotions | Janneke
| 27013801 | Dr. Watson | Carlos
| 27013703 | Big Data Analytics in the Geo Spatial Domain | Romulo
| 27013702 | Jungle-Computing | Jason
| 27013701 | ABC-Muse | Niels
| 27012904 | ODEX4ALL - Open Discovery and Exchange for all | Arnold
| 27012903 | Distributed High-performance AMUSE | Niels
| 27012902 | TwiNL | Erik
| 27012901 | eSiBayes | Jurriaan
| 27012105 | SPuDisc | Jisk
| 27012104 | SimCity | Berend
| 27012103 | Summer in the City | Jisk
| 27012102 | eVisualization of Big Data | Maarten
| 27012101 | Massive Point Clouds for eSciences | tefan
| 27011311 | Water management/eWaterCycle | Niels
| 27011309 | Life Sciences/TraIT | Lars
| 27011308 | BiographyNed/eHumanities | Jisk
| 27011307 | VLBPII/Green Genetics | Lars
| 27011306 | Food Ontologies | Stefan
| 27011305 | eEcology | Stefan
| 27011304 | Biomarker Boosting/ Cognition | Elena
| 27011303 | eSALSA/eClimate | Ben
| 27011302 | eChemistry/Metabolite ID | Lars
| 27011301 | eAstronomy | Rob
......@@ -31,7 +31,7 @@ Make sure the item you want to add has some sort of identifier such as a DOI or
a URL; without it, whatever you're adding is just hearsay.
1. Synchronize with the Zotero server.
1. On the right-hand side, select the ``Miscellaneous`` folder (or, you could try to find a more appropriate folder, but
1. On the left-hand side, select the ``Miscellaneous`` folder (or, you could try to find a more appropriate folder, but
know that that won't matter for anything related to the Research Software Directory -- it does not use the folder
structure from Zotero, just the items that are in it).
1. Click the `Add by identifier` button.
......@@ -46,14 +46,14 @@ correct, as follows:
1. Verify that the `Item Type` (top of the list) is correct.
1. For some `Item Type`s, you need to fill in `Type` as well (see the list below).
1. Verify that any names have been entered correctly, for instance in the `Author` or
`Programmer` fields. We are using the `firstname`, `lastname` format, where each
is in its own input field. You can switch between single and two field entry by
`Programmer` fields. A person's first name and last name each have their
own input field. You can switch between single and two field entry by
pressing the small button next to the names. Name particles (`de`, `van der`, etc.)
should be included in the lastname so for `Jan de Groot` use lastname `de
Groot`.
1. Verify that the dates have been entered correctly. Use a single date (don't
use date ranges). Because dates are tricky, Zotero shows a string such as
`y m d` or `d m y` next to each date, to show what each number represents.
`y m d` or `d m y` next to each date, to show how it has interpreted each number.
1. If everything looks good, synchronize with the Zotero server again.
......@@ -62,32 +62,28 @@ correct, as follows:
Below is a list of output we would like to keep track of, with a short
description. Pick the one that best describes your output, and fill out the
metadata required. By default Zotero shows a much larger list of metadata,
please fill out the others entries as good as possible.
use your judgment to fill out the other fields as necessary.
If you have an item that doesn't fit, please [open an issue
here](https://github.com/research-software-directory/research-software-directory/issues) and we'll figure it
out & update this document.
out and update this document.
### Software
You don't need to add `Software` items to Zotero. We keep track of our software
output via the Research Software Directory. If you have a software package that
you want to add, use the Research Software Directory's Admin interface as
explained [here](README.md).
explained [here](entering-data.md).
### Papers
If you have a DOI, use the 'Add by identifier' button, and check that the ``Item type`` in the ``Info`` tab says either
``Journal Article`` or ``Conference Paper``. Depending on the domain, there may be differences between the two
categories, choose the one you think is most appropriate for your paper.
If you have a DOI, use the 'Add by identifier' button, and check that the ``Item type`` in the ``Info`` tab is correct.
### Datasets
Datasets will be a new feature in an upcoming Zotero release. For now, set
`Item Type` to `Journal Article`.
If you don't have a DOI for the dataset yet, make sure to [upload a copy of the item
to Zenodo](https://zenodo.org/deposit/new), FigShare or an other place that provides a DOI. The item's URL should
point to [https://doi.org/&lt;yourdoi&gt;](https://doi.org/<yourdoi>).
to Zenodo](https://zenodo.org/deposit/new), FigShare or an other place that provides a DOI.
Set `Item Type` to `Web page`, and set the item's URL to [https://doi.org/&lt;yourdoi&gt;](https://doi.org/<yourdoi>).
### Conference poster or presentation slides
......@@ -119,4 +115,4 @@ A PhD, Master, or Bachelor thesis. Set `Item Type` to `Thesis` and fill in
Please choose the most appropriate type from `Blogpost`, `Book`, `Book Section`,
`Interview`, `Magazine Article`, `Newspaper Article`, `Podcast`, `Radio
Broadcast`, `TV Broadcast`, `Video Recording`, `Webpage`. And make a best effort
at filling out the other metadata on the `Info` tab.
attempt at filling out the other metadata on the `Info` tab.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment