Add AI documentation

[InAnYan]

[InAnYan]

Hmm, you say that the general structure is too technical. You mean the blog post or documentation?

In both case, I can't really understand what is technical and what is not. Like, how can I simplify it further?

I don't really like the idea to describe parameters in one sentence, as:

1. It leaves the users with more questions than answers
2. It doesn't provide enough information on how it works, why we need it and what are the consequences of changing a parameter (consequences are probably more important)

[InAnYan]

Oh, and also why AI is not advanced?

• It's the thing that expresses the internals of AI functionality (similar to en\advanced\fields.md that explains different BibTex fields and more).
• It's the thing that you usually don't touch (like most of the time user spends in GUI, but not using the command line en/advanced/commandline.md.

[koppor]

Hmm, you say that the general structure is too technical. You mean the blog post or documentation?

I don't know, who "you" is here. - I meant the user documentation. This pull request here.

The blog post is discussed at https://github.com/InAnYan/blog.jabref.org/blob/ai-1/_posts/2024-07-01-AI-chatting.md

[koppor]

Oh, and also why AI is not advanced?

I didn't find the text I wrote, therefore, I rephase.

1. I assume a user of the documentation DOES NOT follow the blog posts
2. I assume documentation is updated
3. I assume the AI feature will be in JabRef in 2030
4. I assume a reader does not read blog posts of 2024 in 2030 to understand the main idea

Thus, the documentation should introduce the AI feature

The AI feature is a prominent tab in the entry editor. It appears on first start. Thus, it should be explained "easily".

The AI feature will be an important, well-working feature of JabRef. Thus, it should be explained.

I agree that some special settings of OpenAI might be detailed. I think, the should be at the second part of the AI documentation, but the first part should be some intro part.

* It's the thing that expresses the internals of AI functionality (similar to [en\advanced\fields.md](https://github.com/InAnYan/jabref-user-documentation/blob/ai-1/en/advanced/fields.md?rgh-link-date=2024-07-06T18%3A16%3A47Z) that explains different BibTex fields and more).

I think, I also wrote, that we as team should move that somewhere else. I was thinking of https://www.bibtex.org/ even. In "advanced" it is the wrong position. Users should really be aware of the meanings of the fields. However, the current explanation is not made for normal users (e.g., not a grouped explanation, but some random-appearing collection).

* It's the thing that you usually don't touch (like most of the time user spends in GUI, 

I repeat: The introdcution text of AI and some explanations of the inner works have to be in the user documentation.

I add: I agree that detail configurations are not meant for the average users. -- I think, the AI documentaiton can be on one page and not on two pages (into in root and settings in advanced). Reason: I think, that people can scroll and know when to step reading. -- We need to write the page from high-level (intro text) to lower level (details).

[InAnYan]

@koppor I had an idea, but was more focused on fixing bugs in ai-pr-1 pull request.

What about this:

1. Parameters: enable chatting with attached PDF files and OpenAI token are out of Expert settings. What if we put the explanation of these parameters inside ai/ai.md. Inside Enable chatting with attached PDF files we will put the introduction text to AI features.
2. Every other parameter is inside Expert settings section. What if we put the documentation for those parameters inside ai/expert-settings.md?

[koppor]

What about this:

I miss the "why" there. AKA "reasoning" AKA providing rationales.

My reasoning for one page was:

I agree that detail configurations are not meant for the average users. -- I think, the AI documentaiton can be on one page and not on two pages (into in root and settings in advanced). Reason: I think, that people can scroll and know when to step reading. -- We need to write the page from high-level (intro text) to lower level (details).

Which point do you have another opinion? Why do you think, splitting up things is easier?

There is one preference page. Thus, there should also be one page explaining each element.

Note that GitBook offers a side pane.

---

See https://medium.com/olzzio/y-statements-10eb07b5a177 for more motivation, why one should reason about options.

[koppor]

Pleae also take the time to fix the markdown lint issues:

Error: en/advanced/ai.md:23:151 MD009/no-trailing-spaces Trailing spaces [Expected: 0 or 2; Actual: 1]
Error: en/advanced/ai.md:79:349 MD047/single-trailing-newline Files should end with a single newline charact

You can see it at the github output when clicking on "Details".

You should install markdown-lint on as vs code plugin. Long text: To have automatic editor support, this PR adds markdownlint as recommended plugin for VS.Code.

[koppor]

Please link the privacy policy of JabRef where the AI providers will be listed, too.

[InAnYan]

:flushed: