Restructure documentation

[tobiasdiez]

The help should be restructured. Based on this manual and the current structure, I would propose the following:

• Introduction (short description of JabRef, structure of the help)
• Getting started
  • Installation
  • Desktop interface (basic description of the user interface elements and what they do)
  • Quick start (basic userflow: create new library -> add entry, link file, do web search -> save)
• Guides (describe use cases; shouldn't be too in depth, just outline how to do each action and link the later articles for more details, see e.g mendeley guides or this article)
  • Adding items (new entry + manual adding, drag & drop files, import)
  • Web import (fetcher, add based on identifier, download PDF based on entry, browser extension)
  • Organization (groups, search, add keywords, mark entries as read + rank them)
  • Clean-up database (complete entries using fetcher, cleanup, integrity check, file rename & move, find + merge duplicates)
  • Share (file based > use dropbox and the like to sync, export, sql database)
  • Cite-as-you-write (Word, OpenOffice, Latex editor integration)
• FAQ
• Contribution guide
• Changelog
• Details (describe features in detail)
  • essentially everything that we have so far
  • combine a few pages (not every identifier or web fetcher needs to have its own page)

@JabRef/translators @domwass @Codeberg-AsGithubAlternative-buhtz @wujastyk @j0hannes @bernhard-kleine further suggestions what to include or leave out from our power-users? Any features that you discovered on your own but would have like to be told about before?

[wujastyk]

I hope the new manual will be done at Github so that users can participate by cloning and issuing pull requests. It's difficult to think about the content in the abstract, but the outline looks good.

[koppor]

Internal remark:
Follow up to https://github.com/JabRef/help.jabref.org/issues/178

@wujastyk Yes, it will. Same as this repository. Currently not that much contributors, but I'm looking forward positively!

[buhtz]

Please don't take my comments as inpolite. I mean it constructiv. My english is not the best, so I hope you won't take it to rude. Please do not try to "hear" some tones between my lines.
I am strongly interested in improving JabRef and positining it as concurrenc against Mendely, Endnote, Citavi & Co.

First of all I believe in that a software should and can describe itself. The GUI (or any other type of interface) should be able to guide the user that way that it is not possible to read one line of documentation. But this is religion and not reallity - I know. But it should be a far away goal. Even if we could fullfill 50% of that goal it would be great.
And I also take into account that JabRef is a complex software with a complex topic. We can not abondon of the complete documentation.

We also have to take into account that the core devs of JabRef are doing everything in freetime (beside their family and jobs) and the team is kind of overloaded. The question is how much time ressources should they detour from developend and invest into documentation?

The reality: User do not read documentation before they use a software. Even if they have a problem they do not read it. So why should you/we invest time into user documentation?

I would recommand not to write a full complete manual type document. I would recommand to focus on the most common problems users aks and report.

The proposal of Tobias still flow into this direction. I really like the approach to describe features by use cases (Tobias named that section Guides).

What I would completely remove is the Introduction. Installation should not be needed to described. It should be self describing fitting to the related plattform. Of course you need a how to install developer version or from source section. But I would put that in a separate developer documentation and strictly separate that from the user docu.
The same with the contribution and changelog section.
If a user need a description of the Desktop Interface: something is wrong with the GUI.

The FAQ should be combined with a Troubleshooting (or known/often problems) section.

btw: Users like video tutorials.

[j0hannes]

I would prefer the online documentation to follow the menu structure (assuming that the menu reproduces some inherent structure). The next step would be to define a hotkey for help (say Ctrl) and jump to the help entry of that particular menu on click. Technically, a kind of wiki would be more helpful than a single PDF document (especially for searching, linking, opening some entry in a separate tab etc).

I also like the idea of workflows (or guides), but they need to be comprehensive to be helpful, that is, covering also potential borderline cases rather than just the main use case.

[koppor]

Currently http://help.jabref.org was meant to offer what you described. - In 2015, the help was incloded in JabRef. With JabRef/jabref#724, we extracted it out of JabRef and moved it to https://github.com/JabRef/help.jabref.org.

One could also maintain both: help.jabref.org with the direct explanation of the menu entires / buttons / dialogs. For "user stories", it points to https://docs.jabref.org (maintained at https://github.com/JabRef/docs.jabref.org).

[Siedlerchr]

Don't fogert that the help-buttons in JabRef (e.g. next to fields) open the context sensitive help, e.g. describin the dialog options/the action

[wujastyk]

The current English documentation at help.jabref.org is written using the second-person pronoun. "If you want to do this, you do that." I consider this excellent practice, and I hope it will continue into the new documentation effort. The old-fashioned, third-person style, "the user should press return," is rightly to be dumped. :-) Dominik

[mathagician]

Hello @tobiasdiez I can see this issue to be open. Can I take this? If yes, please help me to get started. I know markdown quite well with good English and can start documenting.

[koppor]

@mathagician This is a very hard task. Did you ever use JabRef? Please look at https://docs.jabref.org for the current help. It is contained in the master branch. Feel free to file a proposal against that branch!

[tobiasdiez]

Thanks everyone for the good feedback. I've now restructured the whole user documentation. A few of the new pages are still missing content and/or need to be revised. Help in this regard is very much appreciated. Moreover, the collection pages "Collect", "Organize", etc are currently empty. I think this would be a good place for the use-case oriented guides. I'll opened a new issue for this: #278