OntoPortal documentation requirements and planning

[jonquet]

The OntoPortal workshop 2022 has decided to refactor the whole documentation for OntoPortal (frm user guide to technical documentation, final user doc etc.)
@xeniacs I was suggestion we can start by listing our different documentation pointers here.

[syphax-bouazzouni]

Our current state at Agroportal/SIFR Bioportal

Locally, we started centralizing our docs 10 months ago (see agroportal/project-management#162).

The issues that we had were :

• Which documentation tool to use, that will make the editing easier and still free and easy to deploy (we chose ourtlinewiki)
• We don't have user guides
• There is nowhere developer's documentation (e.g how to set up a development environment, ...)
• A lot of our docs are deprecated

The docs that we use locally for now

• our new centralized doc using outline wiki, see https://doc.jonquetlab.lirmm.fr/share/e6158eda-c109-4385-852c-51a42de9a412
• Some private google docs
• OntoPortal Appliance Administration Guide
• We point also to NCBO docs, NCBO wiki and Bioportal Help
• Scientific papers, see https://github.com/ontoportal/literature
• API documentation, see http://data.agroportal.lirmm.fr/documentation
• Sometimes, we also use Ecoportal docs

My propositions

• We can put all our docs, in the same place. I think OntoPortal Appliance Administration Guide is suitable for that. @ontoportal/bioportal what is your opinion about this? (like you are the mainterns of that doc)
• If we choose the OntoPortal Appliance Administration Guide as our centralized docs, how does it work? I think we need documentation on how to post in the documentation (@ontoportal/bioportal how are you working with it, directly in Gihtub?)
• I think, we should organize our docs, in the following sections: User guides, Administrator guides, Developer's documentation, and lastly DevOps (Infrastructure) ones.
• Optionally: OntoPortal Appliance Administration Guide uses Jekyll with GitHub pages, and Jekyll works with themes (the current used theme is primer (i think)). A nice addition is to use a theme that implements the search feature (see https://jekyllthemes.io/theme/just-the-docs or https://jekyll-themes.com/jekyll-gitbook/)

[jonquet]

Quick note to add that I used to list the different documentation for AgroPortal here: https://github.com/agroportal/project-management/wiki.
We are deprecated this wiki and will be moving this doc to the pages jonquetlab.lirmm.fr @syphax-bouazzouni mentionned.

[jonquet]

+1 on being able to search the doc.

[syphax-bouazzouni]

@ontoportal/industryportal, in the ontportal meeting I think that you @rasmi-aw spoke about documentation that you had done. Could you tell us more about it?

[rasmi-aw]

Hello, it's all about the technical steps to start a project, it's still under construction, i can share the document i'm working on with you if you want.

[syphax-bouazzouni]

Yeah that would be great, because we also working exactly on that, see https://doc.jonquetlab.lirmm.fr/share/81ad0902-e771-4c42-88a5-67202f8ad480

[arsarkar]

@syphax-bouazzouni As Abdel said, he is working on detailed documentation on how to set up not only Ontoportal but also the customisation of Agroportal + O'Faire. It will be really nice to compile the documentation together for all future reference. It is also a good idea to maintain a section called "Commonly known issues" where we can compile all the problems we face and their resolution.

[syphax-bouazzouni]

For " the section called "Commonly known issues" where we can compile all the problems ", there is already this https://ontoportal-lirmm.github.io/documentation/administration/general/faq (same as https://ontoportal.github.io/administration/general/faq/)

[graybeal]

Hi Syphax, thanks for thinking about this. Any "improve this page" link from (lower right of) an OntoPortal Appliance Administration Guide page will take you to the GitHub repo where that doc is maintained. Typically I edit in place (<dodging hand slap>), but sometimes directly on master in my copy of the repo that I then push. Not saying has to be done that way, but when I was the only one… If you go from that GitHub repo page you just landed at and navigate up to the docs<https://github.com/ontoportal/administration/tree/master/docs> directory you can see the readme at the bottom. It's quite detailed. Note particularly the use (abuse) of the diff commenting scheme to get colored comments, which I used religiously to note sections that needed work. (This document was migrated from many internal documents, some of them quite old, so it wasn't trivial to know whether some comments were still valid, or at least useful.) These pages allowed for a lot of automated substitution of variables, which may not have been consistent or valuable enough to continue maintaining, but that's what it is at the moment. We had the search theme enabled at one point (as I recall) but I couldn't get it to work, not sure why not. No reason not to try again. I believe we do have developer documentation, a lot of it actually, but not sure which if any is not BioPortal-specific. (I migrated all the developer documentation that I thought applied to OntoPortal into the Admin Guide.) The dev team can comment on our remaining internal documentation. We must migrate NCBO wiki<https://www.bioontology.org/wiki/Main_Page> and BioPortal Help<https://www.bioontology.org/wiki/BioPortal_Help> but again, it is difficult to know what's still useful. There are some who actually notice when some 12 year old video disappears. We've thought about automating a migration but have never made it a high priority. I like all your proposals, and am fine with them. Except that I think the User Guide should be clearly distinct from the other three, because users will get terribly confused if confronted with all of that in one package. I like either the current Jekyll approach, or an approach based on readthedocs.io<http://readthedocs.io>, which we also have examples of. The advantage of Jekyll is that it is reasonably configurable, and I could imagine blending custom (deployment-specific) documentation in with the other, in an "IF AgroPortal THEN display {content}" or similar style. The over-engineer in me thinks that would be a good way to get everyone invested in a single documentation set, eliminating duplication/stovepipes. But there may be more feasible solutions. I am fine with anyone doing pull requests on the existing documentation, and with sharing ownership with reputable individuals. Obviously a massive overhaul should be a separate branch/workflow.

[jonquet]

Related this issue : agroportal/project-management#162

[rasmi-aw]

Hello sorry about being late to answer, anyway the documentation is still in GOOGLE DOCS, leave me your mails please so i can add all of you as contributors, thanks.

[syphax-bouazzouni]

Hi, the best would be to create a branch here https://github.com/ontoportal/administration (a fork if you don't have the writes) and write it on markdwon, so we can easily integrate into the existent docs.

But anyway, you can find my mail in my GitHub profile https://github.com/syphax-bouazzouni

[jonquet]

Hello everyone, related on this subject I have kicked off a poll here:
#9
Please respond.

[stdotjohn]

I have started some documentation for first time developers on how to setup their development environment. Last time we did this for Protege, there were several versions submitted by more than one developer before we settled on an approach.

It occured to John that a logical place for this document was somewhere on the OntoPortal github as it is very relevant to some OntoPortal developers. What do you think?

The temporary location of this document is https://github.com/ncbo/documentation-dev/blob/main/FirstTry.md

[stdotjohn]

When I first broached this topic to Syphax, he made the following comments:

• • In your file, you said : «  In order to expect anything to work one needs to have the infrastructure running. This can be quickly provided by docker but some of out developers have it running on their development machines », I think except you at Bioportal no one of the alliance is able to do that (to complex for some dependencies like 4store). Thereby we need to focus more in the docker part of your doc (or using the appliance as a backend for local development)

• Lastly,  in your doc, you said: « There are many docker-compoee files that create a running infrastructure. I use the one in the bioportal-config project (which for this purpose is unfortunately private) ». Please share them with the alliance  if possible.
  

I am now working on making the docker files available. The main reason that they are private is that they are deemed not ready. After that the rest should be easy.

-Timothy

[stdotjohn]

The one comment of Syphax's that I had comments on was this one:

• I think we should separate the development documentation from the tests one.

I don't see my document as describing how to run the tests but how to run the tests inside the development environment. Running the tests outside development is a separate issue and should be described in a separate document. I spend and will continue to spend a lot of my development time working with tests which is why I spent so much time on it in the document. Running tests inside and outside a development environment put different stresses on docker and may result in differing docker images.

-Timothy

[stdotjohn]

One approach to the docker question is that I could try to write my own docker image for the infrastructure. I am not sure how long that would take...

[stdotjohn]

I made a pull request to add the development docs (ignoring kramdown) to the administative ontoportal git hub for your consideration.

[xeniacs]

Current status of EcoPortal documentation

EcoPortal has its documentation collected in a dedicated repository at https://github.com/lifewatch-eric/documentation/wiki .
This public version was concluded in October 2021. Several issues and reasons to update have risen since then:

1. EcoPortal recently (November 2022) underwent a major upgrade and documentation lags behind.
2. Several sections are more laconic than a first-time user would need.
3. Several sections retained the BioPortal documentation, which doesn't always correspond exactly to what we have in EcoPortal, e.g. for the metadata.
4. When describing EcoPortal's functionalities for papers or when needing to use the tools for scientific purposes, the scientific work behind each tool and details on the "how"s and the "why"s are of utmost importance, but this info is not readily found in the documentation.

I also refer often to the paper we presented at a conference in 2021, as it gives a good overview and context that is not found in the documentation.

Suggestions for the OntoPortal User's Documentation - not urgent, just ideas

1. Section for first-timers to the portal, with info of the context and the reason of the repository's existence. Use cases, projects, planned work, etc would also be included here. Generic for OntoPortal, but each portal could then add its own.
2. Concise vs extended documentation: something like "read more" under each section
3. A section like "the science behind", where users can read about the scientific work involved in the development of OntoPortal and its instances. This and the "read more" sections would possibly share common parts.

[xeniacs]

The "mapping" of the OntoPortal functionalities to the phases of an ontology's development workflow that we presented at the Workshop could go under the section for context and reason-for-existence. Not in the form of slides though.

[xeniacs]

Resources from the OntoPortal Workshop in Montpellier, Sept 2022, that are relevant to the documentation

OntoPortal Appliance deployment and configuration - @alexskr is this the correct link or is there an updated one?

How to manage infrastructure and convert the OntoPortal Appliance to containers or other VM System - what is Alexandru's github user? I don't see him on the People's list.

I think these two were the only resources relevant for the documentation. Unless we include a Use Cases section, where we summarise info from the presentations, e.g., per field of interest.

[syphax-bouazzouni]

Hi, all

Happy to inform you that we merged the new doc template 🎉 (see ontoportal/documentation#4), and it available here: https://ontoportal.github.io/administration/

Next would be

• Change the repository name from "administration" to "documentation" documentation#9
• Update the new documentation home  documentation#10
• Add a "how to contribute to the documentation" documentation#11

[jonquet]

@galviset said: With an upcoming support of several languages in the interface of portals brought by AgroPortal, it naturally brings the question of doing it for the documentation as well.
It might not be as relevant for developers/maintainers than it is for users, but this idea is more concerning a future user documentation.

[jonquet]

Another pahe of Doc: https://vocabulaires-ouverts.inrae.fr/2022/11/18/publier-vocabulaire/

[galviset]

A possibility to share common doc while keeping some specifics to some OntoPortal instances, I thought about the following:
we could have a system where we setup an "documentation environment" for each portal. The common parts will be displayed in all of them - which requires to agree on a base structure. But then, when switching from one portal documentation to another, specifics then apply:

The content of these screenshots is just there as an example.
Users could simply select the portal they want directly on the top, and it applies all necessary changes. On the first screenshot, this is BioPortal documentation. On the second screenshot, this is EcoPortal documentation and as you can see VocBench shows up since it's specific from EcoPortal.
In the backend, that could be managed by variables which contains specific parts of the documentation, similarly to how language is managed in the AgroPortal UI. This can be useful for several cases: screenshots of a specific portal UI even if it's common documentation to avoid confusing the user with a UI they are not familiar with, or additional documentation for a feature that is only on this portal.

[jonquet]

I like this last idea: @galviset would you need some technical support to do a demo page?
@Bilelkihal @syphax-bouazzouni We should discuss this next AgroPortal meeting.

[galviset]

@jonquet I'm not very experienced with Jekyll so I would gladly accept some help for this.