JabRef's documentation ported to GitBooks

[mlep]

Like Crowdin for the GUI, ReadTheDocs could help in maintaining JabRef's documentation (translations included). More details at https://readthedocs.org

[tobiasdiez]

or maybe https://www.gitbook.com/ or https://readme.readme.io/v2.0/docs/open-source (especially the latter seems to be the go-to solution)
We should evaluate what features each site provides and then evaluate. For me, the most important criteria are:

• easy for users to contribute
• should be easy to customize (so that we can align the style with our main webpage)
• search + navigation features (that is something I currently really miss)
• multi language support

@mlep Do you have some time to have a look at these services and compare them? I would suggest that we then migrate a few pages, play around with it and see if we like it and finally migrate everything.

[mlep]

@koppor: I have just noticed that JabRef's help is ready to be translated via Crowdin: https://crowdin.com/project/jabref-help
However, nobody has started using it while this project is already 11 months old. So I am wondering about the status of this project.

[koppor]

@mlep Unfortunately, the current project structure does not allow to be easily translated. We first should move to an up-to-date help solution and then work on crowdin.

[tobiasdiez]

I played around a bit with readme.com and have to say I really like their interface

https://jabref.readme.io/

Only disadvantage I've found so far is that users have to have an account there in order to suggest edits (also, it's not git based and thus the procedure is somewhat simpler for normal users). Moreover, translation support might be a bit tricky (https://docs.readme.com/docs/language-support) but to be honest - I don't see us having the resources to maintain a high-standard documentation for more than one language.

What are your thoughts? Should we proceed to migrate to readme.com or to somewhere else?

[Siedlerchr]

https://docs.readthedocs.io/en/stable/guides/manage-translations.html
Read the docs has the ability to generate pot/po files.
And crowdin support those as well:
https://support.crowdin.com/supported-formats/

[koppor]

I would like to have easy translations. Especially because of JabRef/manuals.jabref.org#1. We should have at least German and English. Reason: For German undergrade students, German is more easy to read than English. Some Tex users are also more German-friendly. This is still one of our main groups.

[tobiasdiez]

The German (as well as nearly any other translated help page) was not updated in the last 3 years. I'll be positively surprised if there is considerably more effort into the translation in the next 5 years (especially given that more and more people have no problem with english - especially young undergrads).

readthedocs is also fine with me, it's just that readme.io feels more polished. Just let us move forward with something since both options are definitely better than what we have right now.

[tobiasdiez]

ok, I played a bit more, this time with gitbook. It looks like it supports everything that we need: custom domains, free for open source, support of translations via crowdin (see https://github.com/DjangoGirls/tutorial for an example), has a nice UI, github sync.

So if you guys are ok, I'll migrate the help this evening.

[koppor]

Yeah. The only concern is the search at the mobile view. Think, this can be fixed. (Screenshot will be added later)

[koppor]

I also thought about using another static site generator (Hugo, ...). I think, however, that the search still won't work and that it causes more than two hours for a search and evaluation.

[matthiasgeiger]

Yes, gitbook looks promising!

[tobiasdiez]

I've now ported the help to gitbook: https://jabref.gitbook.io/jabref/ Looks quite good in my opinion (although the help content sadly doesn't get better by migrating :()

Only problem is the multi-language support. I was wrong in that the old gitbook supported translations. Sadly, the new one does not, see feature request. So what should we do? For me this was not an important point, but for some of you it was...

[Siedlerchr]

Example of read the docs with a nice layout
https://fiware-orion.readthedocs.io/en/master/#welcome-to-orion-context-broker

[koppor]

😢

It is very important to me.

@mlep - Your take on a French help of JabRef --> https://help.jabref.org/fr/ - Will anyone ever use it?

[koppor]

I knew that I read something about a page generator at my last take on this. It was MkDocs used by redthedocs.

[koppor]

The readthedocs port:

• Badge for stub pages encouraging to contribute (was nice; if we are forced to remove it, we should remove it)
• Badge for outdated pages (this was nice for contributors to have a starting point. It is more difficult to go back the git history to search for some deleted content to start with than starting with something that is partially outdated)

Maybe, I just have to sit down on the Jekyll-Theme itself. Now that I know how to execute Jekyll on GitHub Workflows: https://github.com/JabRef/www.jabref.org/blob/master/.github/workflows/publish.yml

[tobiasdiez]

Gitbook syncs with the markdown files so that every change is visible here in the github repository. Hence, we can also just keep the current help pages for the other languages and link them. For crowdin and the translation progress nothing changes. In this way, the translated help is still accessible (although it doesn't look as nice as the English one) and as soon as gitbook supports multi-languages we migrate them over.

[koppor]

I still need to fully activate crowdin. See https://github.com/JabRef/help.jabref.org/issues/233.

[tobiasdiez]

Or just wait with crowdin until gitbook supports multi-language files. This might make things easier as gitbook might take care of non-existing/non-translated files etc. In my opinion, we have more important issues than to make the help pages translatable via crowdin...

[koppor]

If we accept that we don't have the "outdated badge" any more, we can go ahead. - We can still switch back (accepting that the URLs will change).

We also need to change the help URL in JabRef accordingly. This is what we wanted to avoid (@matthiasgeiger). Otherwise, all users wihtin JabRef will see help.jabref.org in all languages (refs JabRef/jabref#2083).

I like the new layout of GitBooks. So, we should go ahead and accept changing urls and attachment to a commercial page.

[tobiasdiez]

gitbook supports custom domains, so I guess nothing needs to change there (maybe for the translated pages?)

[koppor]

How can I access the French help on GitBook? --> https://jabref.gitbook.io/jabref/fr is 404.

[koppor]

I thought, we use jabref.githook.io for the new English page and keep help.jabref.org for the other languages. This could be done with approx one hour effort on my side (syncLang.py has to be adapted accordingly).

• Switch to Jekyll running on GitHub workflows
• Tell Jekyll that all english help pages are redirected to gitbook.io
• Remove all redirects to english help pages in other languages (syncLang.py!)
• Sync with crowdin

Result: Untranslated help pages in other languages will appear in our layout in the respective URL (instead of a redirect to the English help page).

[tobiasdiez]

https://docs.gitbook.com/integrations/github/content-configuration#redirects would also be an option.

For some reason it is however not working with the french translation:
https://jabref.gitbook.io/jabref/fr/remote
but the english redirection works:
https://jabref.gitbook.io/jabref/en/test
I guess the target file has to be mentioned in the SUMMARY.md.

So, probably what you suggest is the easiest solution. However, I would move the new english help to docs.jabref.org - looks more professional than keeping the gitbook url. Note however that also the english urls changed because of the grouping: e.g. it would be faq/faqcontributing instead of faqcontributing.

[koppor]

When moving to gitbook / readthedocs / ..., we also accept that we cannot use traffic analysis such as https://simpleanalytics.com/ (https://simpleanalytics.io/?ref=github). https://docs.simpleanalytics.com/your-privacy-policy. Example output: https://simpleanalytics.com/simpleanalytics.com

[koppor]

We should rename all help pages then...

Should be rename our repository, too? Meaning, help.jabref.org redirects to docs.jabref.org?

(I also like docs.jabref.org more... I accept that the docs/ subfolder of JabRef code has the same "name" but different content. Maybe, we render that content at dev.jabref.org? -- still have to move our wiki content to docs/, help page, www page ^^)

[koppor]

Maybe, we should go through page by page and rebuild a new help structure when changing the repo to docs. - would be a good chance to restructure the thing...

[tobiasdiez]

Concerning: https://github.com/JabRef/help.jabref.org/issues/178#issuecomment-541463710
see https://docs.gitbook.com/integrations/google-analytics. Moreover, gitbook provides statistics for every page and search query.

[koppor]

Maybe, the JabRef manual provides ideas for a good start: https://manuals.jabref.org/JabRef-UserManual_de.pdf

We need to think whether we want to have F1 help pages (there for help.jabref.org was the URL) or if we want to have more self-contained texts, where a concrete dialog is more second class. Maybe, the dialogs should be described at docs/dialogs, but the functionality itself (based on use cases / user stories) should be first-class citizen (therefore the url docs.jabref.org).

[koppor]

Created https://github.com/JabRef/docs.jabref.org/tree/master

[mlep]

cry

It is very important to me.

@mlep - Your take on a French help of JabRef --> https://help.jabref.org/fr/ - Will anyone ever use it?

Nobody never complained to me about the French help. So, either it was perfect, or nobody cared...
Is there a mean to have the access statistics for the files of https://help.jabref.org/fr/? (and other languages). That may help in deciding if the effort worths it.

[tobiasdiez]

@koppor could you please add CNAME hosting.gitbook.com to docs.jabref.org. Thanks.

@mlep Good idea! Even as a scientist, you sometimes forget to make data-based decisions. 😄

[mlep]

😆
I am curious to see the results!

Could be useful for English too: The most frequently consulted pages are probably related to issues more often encountered by users. That may drive better explanations (in the help), and places for improvement in JabRef.

[Siedlerchr]

See #236 for statistics

[mlep]

So 80% of visitors are consulting the help in English. About 10% for German, 5 % Indonesian and 3% Japanese. Finally, French and Chinese only 2% each.
So, to me, it looks like only the help in English should be on the todo list. Google translate is available for the non-English speaking users (such as the few French speakers).

Could you provide the statistics for the various file in the en/ directory?

On a related matter: could we also have some usage statistics on the UI language settings?

[Siedlerchr]

I will upload more detailed stats later.
Note that this was just usage for one month (September 18 to October 18, 2019)

[tobiasdiez]

@koppor so what is still missing right now to fully migrate to gitbooks? I don't want to wait to long since otherwise the old and the new doc have diverged too much making it harder to switch.

[koppor]

We need a devcall on this.

Currently, I understood it that someone needs to sit down and port the whole content in a new structure to docs.jabref.org. Details are provided at: https://github.com/JabRef/help.jabref.org/issues/235

We also need to wait for multi-language support: https://github.com/JabRef/help.jabref.org/issues/234

After someone created content for docs.jabref.org, one can link the sections from help.jabref.org (and remove the contents there). Maybe the one porting can do that in parallel.

The other languages are somehow blocked by #234. Maybe, I have to create different repositories. However, I don't think that Crowdin allows for multiple repositories.

[koppor]

https://docs.jabref.org/ is now life. - However with old files. Need to do following:

1. Move content from en folder to other folder (see master branch)
2. Redirect from help.jabref.org/en/* to the right docs.jabref.org page (Example: https://docs.jabref.org/fields/journalabbreviations) - famous automate.py script.
3. Have it all available at the master branch only.

[tobiasdiez]

Concerning point two, these redirects can also be configured using gitbook:
https://github.com/JabRef/help.jabref.org/blob/master/.gitbook.yml#L10
http://docs.jabref.org/en/test

so a global redirect of help.jabref.org/en to docs.jabref.org/en and a few lines in .gitbook.yml should be enough.

[koppor]

Thinking longer of it, I think, we can drop the non-English files for now. After we finished the restructuring of the help (refs #235), we can think of going forward with translations again. Up to that, it does not make sense, because there are many outdated pages in the other languages - and also in the English language.

[koppor]

The good news is that the JabRef help is finally available at https://docs.jabref.org.

abRef org members can request access to https://app.gitbook.com/@jabref/s/jabref/. Then, they can do live editing - this is very impressive

Thank you @tobiasdiez for pushing forward. On the one hand, I am sad that we lost the translations (for now). On the other hand, I am happy, that the search works great, the mobile experience is great and that we have live editing!

[tobiasdiez]

Thanks for your work on this! Looks really good.

What you think about renaming this repo to User Documentation?

[koppor]

• Repository renamed
• Redirections in place. Some direct, some indirect: E.g., http://help.jabref.org/en/StringEditor points to https://docs.jabref.org/?q=String%20Editor