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?