OpenMS · tapaswenipathak · May 29, 2022 · May 29, 2022 · May 29, 2022 · May 29, 2022
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
@@ -27,7 +27,22 @@ For any questions, drop us a ping in [OpenMS Gitter](https://gitter.im/OpenMS/Op
 2. Restrict the line length to 120 characters, including space(s).
 3. Title and H1 heading should be in `Title Case`. Follow `Sentence case`, until otherwise stated.
 4. Write as OpenMS is writing for itself as an object and subject.
-5. Be nice, polite, and respectful.
+5. Use American English.
+6. Use `backtick`(s) for formatting code, library name, files, and path.
+7. Use **bold** for product name, object name, an independent entity.
+8. Use **bold** for menu title in an application.
+9. Link to glossary terms using {term}`this is a glossary term`.
+10. OpenMS documentation uses following Admonitions
+    - Hint
+	- Important
+	- Note
+	- Warning
+	- Tip
+	- See Also
+	Example of these are present in documentation, please follow them.
+11. Always specify lexers for code blocks.
+12. Format keyboard strokes using `<kbd>qwerty-keyboard-button</kbd>`.
+13. Be nice, polite, and respectful.
 
 ### Naming files
 

diff --git a/.github/ISSUE_TEMPLATE/feature-request.md b/.github/ISSUE_TEMPLATE/feature-request.md
@@ -13,14 +13,14 @@ Thanks for suggesting a new feature for the OpenMS Documentation!
 Please delete this text and anything that's not relevant from the template below:
 -->
 
-## Is your feature request related to a OpenMS Documentation problem? Please describe 
+## Is your feature request related to a OpenMS API Reference Documentation? Please describe.
 
-<!-- 
+<!--
 
 For feature request in OpenMS, please create issue in [OpenMS](https://github.com/OpenMS/OpenMS/issues)
-Please provide a clear and concise description of what the problem is in documentation. 
+Please provide a clear and concise description of what the problem is in documentation.
 -->
-- [ ] I have attached screenshot describing the problem, if applicable
+- [ ] I have attached screenshot describing the problem, if applicable.
 
 ## Describe the documentation enhancement you'd like
 

diff --git a/docs/advanced-resources/custom-compilation.md b/docs/advanced-resources/custom-compilation.md
@@ -5,15 +5,14 @@ To compile with self built compilers and non default standard libraries, follow
 
 To choose any specific compiler, instead of the system default, add the whole path to these options for the cmake call:
 
-- GCC:
-  ```bash
-  cmake -DCMAKE_C_COMPILER=/path/to/c-compiler/binary/gcc -DCMAKE_CXX_COMPILER=/path/to/c++-compiler/binary/g++
-  ```
+```{tab} GCC
 
-- Clang:
-  ```bash
-  cmake -DCMAKE_C_COMPILER=/path/to/c-compiler/binary/clang -DCMAKE_CXX_COMPILER=/path/to/c++-compiler/binary/clang++
+`cmake -DCMAKE_C_COMPILER=/path/to/c-compiler/binary/gcc -DCMAKE_CXX_COMPILER=/path/to/c++-compiler/binary/g++`
   ```
+```{tab} Clang
+
+`cmake -DCMAKE_C_COMPILER=/path/to/c-compiler/binary/clang -DCMAKE_CXX_COMPILER=/path/to/c++-compiler/binary/clang++`
+```
 
 To compile OpenMS with clang and a specific GCC stdlib, instead of the system default one:
 

diff --git a/docs/glossary.md b/docs/glossary.md
@@ -11,7 +11,7 @@ Peptides
   A short chain of amino acids.
 
 Octadecyl(C18)
-  An alkyl radical C~18~H~37~ derived from an octadecane by removal of one hydrogen atom.
+  An alkyl radical C(18)H(37) derived from an octadecane by removal of one hydrogen atom.
 
 Mass
   Mass is a measure of the amount of matter that an object contains. In comparison to often used term weight, which is
@@ -59,4 +59,89 @@ Collision-induced dissociation (CID)
   A mass spectrometry technique to induce fragmentation of selected ions in the gas phase. Also known as Collision
   induced dissociation.
 
+TOPP
+  The OpenMS Proteomics Pipeline.
+
+TOPPAS.app
+  TOPPAS allows to create, edit, open, save, and run TOPP workflows.
+
+MSGFPlusAdapter
+  Adapter for the MS-GF+ protein identification (database search) engine. More information is available [here](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/TOPP_MSGFPlusAdapter.html).
+
+LuciphorAdapter
+  Adapter for the LuciPHOr2: a site localisation tool of generic post-translational modifications from tandem mass
+  spectrometry data. More information is available [here](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/TOPP_LuciphorAdapter.html).
+
+pyOpenMS
+  pyOpenMS is an open-source Python library for mass spectrometry, specifically for the analysis of proteomics and
+  metabolomics data in Python. For pyOpenMS documentaion visit [this](https://pyopenms.readthedocs.io/en/latest/) link.
+
+TOPP Tools
+  All {term}`TOPP` tools can be found [here](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/TOPP_documentation.html).
+
+UTILS
+  Besides TOPP, OpenMS offers a range of other tools. They are not included in TOPP as they are not part of typical
+  analysis pipelines. More information is present in [OpenMS UTILS Documentation)(https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/UTILS_documentation.html).
+
+TOPPView
+  TOPPView is a viewer for MS and HPLC-MS data. More information is available in [TOPPView documentation](topp/toppview.md).
+
+[Nightly Snapshot](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/index.html)
+  Untested installers and containers are known as the nightly snapshot.
+
+Proteomics
+  Proteomics is the large-scale study of proteins.
+
+Proteins
+  Proteins are vital parts of living organisms, with many functions, for example composing the structural fibers of
+  muscle to the enzymes that catalyze the digestion of food to synthesizing and replicating DNA.
+
+Mascot
+  Identifies peptides in MS/MS spectra via Mascot. Please find more information in the {term}`TOPP` [Documentation](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/TOPP_MascotAdapter.html).
+
+HPLC-MS
+  Data produced by High performance liquid chromatography (HPLC) separates components of a mixture, whereas mass
+  spectrometry (MS) offers the detection tools to identify them.
+
+mzML
+  The mzML format is an open, XML-based format for mass spectrometer output files, developed with the full participation
+  of vendors and researchers in order to create a single open format that would be supported by all software.
+
+mzData
+  mzData was the first attempt by the Proteomics Standards Initiative (PSI) from the Human Proteome Organization (HUPO)
+  to create a standardized format for Mass Spectrometry data.[7] This format is now deprecated, and replaced by mzML.
+
+mzXML
+  mzXML is an open data format for storage and exchange of mass spectroscopy data, developed at the SPC/Institute for
+  Systems Biology.
+
+Spectra
+  Singluar of spectrum.
+
+Spectrum
+  A mass spectrum is a type of plot of the ion signal as a function of the mass-to-charge ratio. These spectra are used
+  to determine the elemental or isotopic signature of a sample, the masses of particles and of molecules, and to
+  elucidate the chemical identity or structure of molecules and other chemical compounds.
+
+m/z
+  mass to charge ratio.
+
+RT
+  Retention time (RT).
+
+ProteoWizard
+  ProteoWizard is a set of open-source, cross-platform tools and libraries for proteomics data analyses. It provides a
+  framework for unified mass spectrometry data file access and performs standard chemistry and LCMS dataset computations.
+
+OMSSA
+  The Open Mass Spectrometry Search Algorithm (OMSSA) is an efficient search engine for identifying {term}`MS/MS`
+  {term}`peptide` {term}`spectra` by searching libraries of known protein sequences.
+
+PepNovo
+  PepNovo is a de novo sequencing algorithm for {term}`MS/MS` {term}`spectra`.
+
+De novo peptide sequencing
+  A peptide’s amino acid sequence is inferred directly from the precursor peptide mass and tandem mass spectrum
+  ({term}`MS/MS` or {term}`MS^3`) fragment ions, without comparison to a reference proteome.
 ```
+
diff --git a/docs/guides/contributors-quickstart-guide.md b/docs/guides/contributors-quickstart-guide.md
@@ -7,12 +7,12 @@ To contribute to OpenMS:
 - Learn how to [build OpenMS](../installations/build-openms-from-source.md).
 - Check out the [OpenMS tutorial for developers](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/OpenMS_tutorial.html).
 
-For any questions, please [contact us](../contact-us.md) at [open-ms-general]((https://sourceforge.net/projects/open-ms/lists/open-ms-general) mailing list.
+For any questions, please [contact us](../contact-us.md) at [open-ms-general](https://sourceforge.net/projects/open-ms/lists/open-ms-general) mailing list.
 
 ## Technical documentation
 
 ```{note}
-Untested installers and containers are known as the nightly snapshot, are released every night. They generally pass
+Untested installers and containers are known as the {term}`nightly snapshot`, are released every night. They generally pass
 automated continuous integration tests but no manual tests.
 ```
 

diff --git a/docs/guides/user-guides/user-quickstart-guide.md b/docs/guides/user-guides/user-quickstart-guide.md
@@ -7,7 +7,7 @@ information, consult [OpenMS API Reference](https://abibuilder.informatik.uni-tu
 ## What is OpenMS
 
 [OpenMS](https://www.openms.de/) is a free, open-source C++ library with Python bindings. It is commonly used for liquid
-chromatography-mass spectrometry (LC-MS) data management and analyses. OpenMS provides an infrastructure for the rapid
+chromatography-mass spectrometry ({term}`LC-MS`) data management and analyses. OpenMS provides an infrastructure for the rapid
 development of mass spectrometry related software as well as a rich toolset built on top of it. OpenMS is available
 under the [three clause BSD licence](https://github.com/OpenMS/OpenMS/blob/develop/LICENSE) and runs under Windows, macOS, and Linux operating systems.
 
@@ -17,16 +17,16 @@ Before using OpenMS, become familiar with the following terms:
 
 | Tool and Utilities | Description |
 |--------------------|-------------|
-|**TOPPView**        |A design tool that is used to view and explore LC-MS data, alignments, groups, peptide identifications, and more.|
-|**TOPPAS**          |A graphical workflow design tool that is used to create pipelines from all TOPP tools (and UTILS).|
-|**TOPP tools**      |A set of command line tools. Each of these command line tools is a building block of an analysis pipeline and are chained together in a way that fits the requirements of the user. The TOPP tools are accessible from a command prompt/shell or via TOPPAS. See also: [TOPP tutorial](../../tutorials/TOPP/TOPP-tutorial.md) and [TOPP documentation](../../topp/topp.md)|
-|**UTILS**           |Similar to TOPP tools, but with more supporting character, which are rarely used in a productive pipeline, but rather during pipeline construction or parameter optimization. See also: [UTILS documentation](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/UTILS_documentation.html)|
+|**TOPPView**        |A design tool that is used to view and explore {term}`LC-MS` data, alignments, groups, peptide identifications, and more.|
+|**TOPPAS**          |A graphical workflow design tool that is used to create pipelines from all {term}`TOPP tools` (and {term}`UTILS`).|
+|**TOPP tools**      |A set of command line tools. Each of these command line tools is a building block of an analysis pipeline and are chained together in a way that fits the requirements of the user. The {term}`TOPP tools` are accessible from a command prompt/shell or via {term}`TOPPAS`. See also: [TOPP tutorial](../../tutorials/TOPP/TOPP-tutorial.md) and [TOPP documentation](../../topp/topp.md)|
+|**UTILS**           |Similar to {term}`TOPP tools`, but with more supporting character, which are rarely used in a productive pipeline, but rather during pipeline construction or parameter optimization. See also: [UTILS documentation](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/nightly/html/UTILS_documentation.html)|
 
 ## How to run a Tool
 
-A good start are the example pipelines (select **File** > **Open example file** within TOPPAS).
+A good start are the example pipelines (select **File** > **Open example file** within {term}`TOPPAS`).
 
-Read the documentation of the tools (see [TOPP tutorial](../../tutorials/TOPP/TOPP-tutorial.md), [TOPP documentation](../../topp/topp.md) and the one of TOPPAS ([TOPPAS tutorial](../../tutorials/TOPPAS/TOPPAS-tutorial.md)).
+Read the documentation of the tools see [TOPP tutorial](../../tutorials/TOPP/TOPP-tutorial.md), [TOPP documentation](../../topp/topp.md) and the one of ([TOPPAS tutorial](../../tutorials/TOPPAS/TOPPAS-tutorial.md)).
 
 Alternatively, use the command line and call tools directly. In this case, you'll probably want to use some type of shell
 script for automation.
@@ -42,19 +42,19 @@ The default parameters of each tool can usually be tweaked to fit the data and i
 	       file are shown here as well.
 2. **Command line**: Very basic parameters can be set on the command line, e.g. `FileFilter -rt 1000:2000 .....`
 3. Doing 2 for all parameters would create a very long list, thus, use so-called `.ini` files to provide full parameter
-   sets to TOPP tools. If no INI file is given, default parameters are used. To get a default `.ini` use
+   sets to {term}`TOPP tools`. If no INI file is given, default parameters are used. To get a default `.ini` use
 
    `<tool> -write_ini <file>`
 
    e.g. `FileFilter -write_ini filefilter.ini`
 
    Now, edit the INI file (which is a XML file) using the [INIFileEditor](../../topp/ini-file-editor.md), which is another GUI tool shipped with
-   OpenMS and similar to the one build into TOPPAS.
+   OpenMS and similar to the one build into {term}`TOPPAS`.
 
 ### How do I feed the INI file to a Tool?
 
 1. **TOPPAS**: Once you changed the parameters of a node and clicked **Ok**, the parameters are in effect. Because
-   they are part of the TOPPAS workflow, they are saved together with the workflow.
+   they are part of the {term}`TOPPAS` workflow, they are saved together with the workflow.
 2. **Command line** : Supply the INI file via the `-ini` flag,
    `<tool> -ini <file>`
 
@@ -63,4 +63,5 @@ The default parameters of each tool can usually be tweaked to fit the data and i
 ### What parameters to set and to what value?
 
 The answer is complex, in general, read the tool description, change the parameters and compare the results using
-TOPPView if possible. If that does not help, [contact us](../../contact-us.md). Please include all the necessary details we need in order to help you.
+{term}`TOPPView` if possible. If that does not help, [contact us](../../contact-us.md). Please include all the necessary
+details we need in order to help you.
diff --git a/docs/index.rst b/docs/index.rst
@@ -69,8 +69,8 @@ Contents
    :maxdepth: 2
    :caption: Frequently Asked Questions
 
-   developer-faq.md
-   contributor-faq.md
+   faqs/developer-faq.md
+   faqs/contributor-faq.md
 
 .. toctree::
    :maxdepth: 2

diff --git a/docs/installations/build-openms-from-source.md b/docs/installations/build-openms-from-source.md
@@ -7,4 +7,4 @@ To build OpenMS, please follow the build instructions for:
 * [macOS](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/install_mac.html)
 * [Windows](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/Documentation/release/latest/html/install_win.html)
 
-Instructions to build pyOpenMS can be found in the [pyOpenMS documentation](https://pyopenms.readthedocs.io/en/latest/build_from_source.html).
+Instructions to build {term}`pyOpenMS` can be found in the [pyOpenMS documentation](https://pyopenms.readthedocs.io/en/latest/build_from_source.html).
diff --git a/docs/installations/installation-on-gnu-linux.md b/docs/installations/installation-on-gnu-linux.md
@@ -25,7 +25,7 @@ conda install -c bioconda libopenms
 conda install -c bioconda openms-thirdparty
 ```
 
-## Install via Debian Package
+## Install via Debian package
 
 For Debian-based Linux users, it is suggested to  use the [deb-package](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/OpenMSInstaller/release/latest/) provided. It is most easily installed with **[gdebi](https://launchpad.net/gdebi)**
 which automatically resolves the dependencies available in the PPA Repositories.
@@ -59,7 +59,7 @@ If you encounter errors with unavailable packages, troubleshoot using the follow
    `/usr/share/OpenMS/THIRDPARTY`
 5. Add the folders in your `PATH` for a convenient use of the adapters.
 
-## Install via Package Managers
+## Install via package managers
 
 Packaged versions of **OpenMS** are provided for Fedora, OpenSUSE, Debian, and Ubuntu. You can find them to download
 [here](https://pkgs.org/download/openms). For other GNU/Linux distributions or to obtain the most recent version of the
@@ -81,7 +81,7 @@ The source code of OpenMS is available on GitHub. Follow [Building OpenMS on GNU
 Some thirdparty software used via adapter tools in OpenMS might also require an installed JavaVM.
 ```
 
-## Run via a (Bio)Docker Image
+## Run via a (Bio)Docker image
 
 Make sure you have [Docker installed](https://docs.docker.com/engine/install/).
 

diff --git a/docs/installations/installation-on-macos.md b/docs/installations/installation-on-macos.md
@@ -28,7 +28,7 @@ To install OpenMS on macOS, run the following steps:
 
 <img src="https://raw.githubusercontent.com/OpenMS/OpenMS-docs/staging/docs/images/installations/macos/copying-to-applications.png" alt="Copying to Applications" width="500" float: left/>
 
-To use TOPP as regular app in the shell, add the following lines to the `~/.profile` file.
+To use {term}`TOPP` as regular app in the shell, add the following lines to the `~/.profile` file.
 
 ```bash
 export OPENMS_TOPP_PATH=<OpenMS-PATH>
@@ -61,9 +61,9 @@ Follow [these](installation-on-gnu-linux.md#install-via-conda) instructions.
    cd /Applications/OpenMS-<version>
    sudo xattr -r -d com.apple.quarantine *
    ```
-2. Bug with running Java based thirdparty tools like MSGFPlusAdapter and LuciphorAdapter from within **TOPPAS.app**
+2. Bug with running Java based thirdparty tools like {term}`MSGFPlusAdapter` and {term}`LuciphorAdapter` from within **TOPPAS.app**
 
-   If you face issues while running Java based thirdparty tools from within TOPPAS.app, run the TOPPAS.app from within
-   the Terminal.app (e.g. with the `open` command) to get access to the path where Java is located.
+   If you face issues while running Java based thirdparty tools from within {term}`TOPPAS.app`, run the {term}`TOPPAS.app`
+   from within the Terminal.app (e.g. with the `open` command) to get access to the path where Java is located.
    Java is usually present in the `PATH` of the terminal. Advanced users can set this path in the `Info.plist` of/inside
    the TOPPAS.app.
diff --git a/docs/installations/installation-on-windows.md b/docs/installations/installation-on-windows.md
@@ -1,9 +1,9 @@
 Installation on Windows
 =======================
 
-## Install via Windows Installer
+## Install via Windows installer
 
-To Install the binary package of OpenMS & TOPP:
+To Install the binary package of OpenMS & {term}`TOPP`:
 
 1. Download and execute the installer `OpenMS-<version>-Win64.exe` from the [archive](https://abibuilder.informatik.uni-tuebingen.de/archive/openms/OpenMSInstaller/release/latest/) and follow its instructions.
 2. Run the installer under the user account that later runs OpenMS. It is not advised to use admin account for
@@ -14,7 +14,7 @@ The windows binary version works with most versions of windows from Win7 to Win1
   still work but are untested).
 ```
 
-## Known Issues
+## Known issues
 
 1. During installation, an error message pops up, saying "The installation of the Microsoft .NET 3.5 SP1' package failed!