https://github.com/ComPlat/chemotion_ELN/blob/development-5/.env.development

Action needs to be updated to bring it in line with latest versions. See Annotations on this page for more.

As discussed, versioning adds complexity and we don't really need it.

For complete beginners, the ELN lacks a clear entry / starting point (aka "Getting started").
The following sections contain information that could be useful for a "Getting started" section:

Intro
Introduction videos
Structure of the ELN
First steps

However, these sections are not integrated well enough / lack coherence and context.

Expand project overview with up-to-date architecture diagram(s). See for example Figure 1 in https://jcheminf.biomedcentral.com/articles/10.1186/s13321-017-0240-0.
Potential drawing tool: https://asciiflow.com/#/

optional: If the automatic Style Guide Parser detects some offenses against the Style Guide rules (https://www.chemotion.net/chemotionsaurus/docs/eln/styleguide_docusaurus) send an e-mail to the author of the commit. Get the e-mail address from git log or git show and search for an e-mail action in https://github.com/marketplace?type=actions.

Currently, we have a lack of documents about how to work with Analytical data, how to make it run and it's architecture.

With the introduction of new test libraries and approaches, a revision of the test chapter is necessary.

In the details modal of samples, in the analyses tab, datasets window:
It would be great to provide some recommendation of the type of information to be added to the description field.

explain stuff for development with chemotion ELN:

• common errors
• tools, VS extensions etc.
• using Swagger for REST requests

Suggestions so far:

• commit title is meaningful => git history search
• commit description is helpful => helps the reviewer to understand the changes
• code is up-to-date with the latest developments of the target branch (rebased to it or whatever) => ⏩ :-merge for linear history is favored
• added code is linted
• tests are passing (at least locally)
• if the changes are visible to the end-user, video or screenshots should be added to the PR => helps with user testing
• testing coverage improvement is more than welcome
• CHANGELOG : add a bullet point on top (optional: reference to github issue/PR )
• clarify which dependencies are added, if any

• issues with rdkit openbabel native compilation
• multipass ubuntu
• docker

Improve style guide parser based on buggy auto-correction commits such as 50bacf5 or 3eef49b.

https://github.com/tmm1/stackprof
https://github.com/piotrmurach/rspec-benchmark
https://scoutapm.com/blog/profiling-rails-with-stackprof
https://youtu.be/XL51vf-XBTs
https://youtu.be/6uKZXIwd6M0 (5:20-13:00)
https://www.brendangregg.com/flamegraphs.html

As remarked by users at RWTH, the landing page (rendered at https://www.chemotion.net/docs/ and configured at https://github.com/ComPlat/chemotion_saurus/blob/b3bc2d0cecc5e2bfb13fc051551e67749e52d62f/docs/index.mdxt) is currently empty.

@nicolejung, do you have suggestions for content?

Add description on chemotion templates and available standard templates

It would be great to agree on some conventions of writing and gather them in a document for all editors to be aware of. Possible areas:

• Titles: All starts with capital letters or only first word?
• Words in tables, do they start with capital letters?
• Adding images before or after the corresponding paragraph?

The main difference between Samples and Molecules maybe best to be described in https://eln.chemotion.net/chemotionsaurus/docs/eln/samples , but still necessary to show how they are treated differently in the details modal.

Migrate to Algolia DocSearch: https://docusaurus.io/blog/2021/11/21/algolia-docsearch-migration

The results tab is still not implemented, and it needs to be described when it is finished.

• rename Administration to Admin UI
• move/remove corresponding existing paragraphs from https://www.chemotion.net/chemotionsaurus/docs/eln/settings
• have a subsection for each of the admin-ui tabs :
• User Management #343
• Group / Devices
• Data Collection
• NoVnc Settings
• UI Features
• text template management
• Message
• OLS
• Delayed Jobs
• Chemspectra layout

other

• #251
• deprecate docs for report template management

When selecting My Groups -> Create new group in the field Name abbreviation there is a restriction to 2-5 characters. Attempts to enter longer acronyms (German: "Sigel") result in an error message:

name_abbreviation has to be 2 to 5 characters long

This can cause problems, as in our institute for example the NMR department uses by standard acronyms of the format AKX-YZ where X is the first letter of the family name of the PI and YZ are the initials of the corresponding group member. There are also other schemes which are even longer, as the YZ "name space" might easily run out of characters with very large groups.

As these schemes have been in place for a long time it will be very difficult to change them, especially when introducing an ELN institute-wide is already a major disturbance not necessarily appreciated by all long-term staff.

Is it possible to allow a couple of more characters, say 6-8???

We have identified the following minimum requirements for our documentation.

1. There should be specific docs for each version of the ELN

• This is important especially w.r.t. installation instructions, since they have changed considerably throughout versions.
• Legacy docs (i.e., not current version) won't be maintained and only receive critical updates (e.g., security)

2. We need to be able to edit the docs such that changes can be (selectively) made across different versions

- For example, if a change in v3 is benefecial to and also valid for v2 (but not v1), then it should be possible to only apply the changes to v2 and v3.

3. Users should be able to conveniently edit the current version of the docs

- How to ensure that non-functional edits (typos, style) to one version are propagated to other versions?

• How to ensure that we do not clutter our git history with a bunch of minor edits?

4. Developers should be able to conveniently document (new) features

• Ideally, we would like documenting and feature-development as closely coupled as possible.

5. Docs should be available offline

• The offline docs would pertain only to the version that's currently running in the offline environment.
• There should be a way to access the same documentation even if the ELN fails to run i.e. for troubleshooting scenarios.

6. Other related services need to be documented alongside the ELN

• For example, we currently we need documentation for Repo, LabIMotion, ChemSpectra, CLI and ChemScanner.
• We need to figure out how (and if) to integrate the documentation of these services into existing docs.

7. Provide roles for different types of readers of the docs

• Structure docs along the lines of roles, such that it's easier for readers to find what matters to them:
  • developers
  • users
  • admins
  • contributors

🚀 CALL TO ACTION 🚀
Please add additional requirements, remarks and/or suggest solutions as comments on this issue. When proposing solution(s), please clarify how the solution fulfills the above requirements. @harivyasi and I will integrate your contributions in the list above.

Ruby

• https://docs.gitlab.com/ee/development/pry_debugging.html
• https://github.com/ruby/debug

Clarify the lifecycle of an issue on https://github.com/ComPlat/chemotion_ELN, from opening, over prioritization, to PR, and merging into main code.

Status:
multiple instructions with overlapping content written by different authors available:
https://www.chemotion.net/chemotionsaurus/docs/eln/docker_installation (Peter Krauß) https://www.chemotion.net/chemotionsaurus/docs/eln/development_docker_installation (Aaroba Khokar)
https://www.chemotion.net/chemotionsaurus/docs/eln/DevDocker (Frank Broda)

TODOs:

• Jan C. Brammer updated instructions for WSL-2: #29 --> needs to be reviewed & rebased
• unique structure in TOC: Installation/Production & Installation/Development --> move & merge https://www.chemotion.net/chemotionsaurus/docs/eln/DevDocker to other chapters

The deploy job fails intermittently with:

kex_exchange_identification: read: Connection reset by peer
rsync: connection unexpectedly closed (0 bytes received so far) [sender]
rsync error: unexplained error (code 255) at io.c(235) [sender=3.1.3]
Error: Process completed with exit code 255.

We need to work more towards respecting user privacy; especially when embedding items. Ideally loading any page of the documentation should not set any cookies without user permission.

cause: error with Algolia configs, maybe index was reset by Algolia
dev + production mode
status: e-mail to Algolia support was sent, waiting for response

optional: Due to the large growth of our documentation it would be helpful to create roles to highlight which part of the documentation is helpful to whom:
roles could be:

• chemist
• contributor (to the documentation)
• developer (of docusaurus)
• system admin or creator (of docusaurus)

The SciFinder module can be installed from Chemotion ELN plugin, please refer to the installation documentation. The function is currently available for members of Karlsruhe Institute of Technology only. A rework of the API to meet the requirement of SciFinderN will be provided as soon as possible.

Needs to be more specific / actionable.

Thanks for pointing this out @martinschae

(comments from dd4d99b moved here for discussion/change request)

• From how many users should I start splitting the services

• How does this make sense? What advantages do I have?

• Installation scripts for the different machines is missing.

• On the end of the page are important information -> link possible?

• How do I install Chemotion if several working groups at one university / from different universities want to access Chemotion? Does each working group have to install everything completely? Can I save the data of the working groups on different computers?

• Where are the research data and entries stored in Chemotion? If the installation is done on multiple machines, Chemotion will have more users and consequently more data. Shouldn't the DB server have more hard disk or at least 500 GB?

• The information density here is very high, and i think that single subheadings would help, e.g. "Use of SSL" here.
  Another point, e.g. Use of a server name

The SciFinder tab is still not ready, and it needs to be described when it is finished.

• spell-checker
• check for broken links
• enforce line breaks in order to make files easier to work with in editor (i.e., no horizontal scrolling)

At the moment, links are mostly used in the documentation to refer to other chapters when more details are needed. An improvement would be to replace each word described by a chapter or a paragraph by the corresponding link.

• high level decription: what can be achieved with generic elements, which problems do they solve
• 2-3 simple, representative examples

Versioning of the ELN documentation is available:
Current version 0.9: https://www.chemotion.net/chemotionsaurus/docs/eln/videos_eln
Old version 0.8: https://www.chemotion.net/chemotionsaurus/docs/eln/version-0.8/videos_eln

https://github.com/nektos/act

Need to wait for nektos/act#775 in order for PostgreSQL service to work.

Move documentation on continuous intergration from Development/Testing to Development/Continuous integration.

I made some additions to https://www.chemotion.net/chemotionsaurus/docs/eln/settings (Pullrequests 85 and 73) but these changes seem to be gone. Also, there are now two files /master/docs/eln/configuration.md and /master/docs/eln/configuration.mdx.

The docs contain some loose ends (unfinished sections etc.), some of them are marked with comments such as TO DO, #TODO or To be continued....

• make overview of looses ends
• figure out who can finish WIP sections

As suggested by @nicolejung, the sidebar can be more intuitive, especially for the repo section. This issue tracks the progress in this direction.

Remove Ubuntu 18.04 from installation instructions, since ELN is no longer tested against Ubuntu 18.04.

@ptrxyz, as pointed out by @alhoch, https://chemotion.net/chemotionsaurus/docs/eln/settings needs to be updated w.r.t., the Docker installation. Currently, the information pertains to local installs.

We need to keep an overview of technical decisions (architecture, frameworks, etc.): what changed, when, and why?

• introduction of MobX-State-Tree: ComPlat/chemotion_ELN#848
• ComPlat/chemotion_ELN#767
• ComPlat/chemotion_ELN#911

issue: subpages cannot be accessed via bookmark or reloading
intermediate solution until bug is fixed: go to root page (chemotion.net) again & click to subpage

Guidelines on how to review a PR on https://github.com/ComPlat/chemotion_ELN.