Documentation of Web-UI for end users #7297

New Issue

GiteaMirror · 2025-11-02T07:22:22-06:00

GiteaMirror commented

2025-11-02 07:22:22 -06:00

Originally created by @rk-mlu on GitHub (May 5, 2021).

Gitea version (or commit ref): 1.14.1
Git version: 2.20.1
Operating system: not relevant

Description

Dear Gitea developers,

I am a member of an admin team which is responsible for running a Gitea instance to collaborate on projects on a department level at a university. In the wake of the pandemic our user base has increased considerably, and the use cases have developed far beyond our initial intentions to jointly develop code or to write LaTeX documents etc. While we are happy with this development, the increased number of inexperienced Git(-ea) users has also come with some additional obstacles.

Many of our new users do not have any pre-existing experience with other Git environments such as GitHub, GitLab etc. While we are busy in teaching/training them how to use git and integrate it in their workflow, we also received several notifications that the help function of the web UI is often causing frustration, especially, for new users.

For instance, if I click on my avatar in the upper right corner, I am offered a help button, which leads to the Gitea documentation. As an admin, I am quite happy with these docs. However, these pages are not exactly what a first time Git/Gitea user is usually expecting. While we are, of course, offering internal training measures, I have the feeling that the user experience, especially for Git/Gitea newcomers, could be improved without much effort.

My suggestion is: If I click on the 'Help' button as a standard user (it might be different for admins of course), I should be referred to a page which contains some rather basic information about Git and Gitea. For example:

One could mention, for instance, that Git and Gitea are actually two different things.
There should be a reference to free Git resources, e.g., the Git book. It is perfectly fine, imho, that the Gitea community does not offer any user support on git itself, but the main help page may refer a new user to places where he or she finds some support.
A user (not admin) centric FAQ would also be appreciated with questions that are gitea-web-ui related (like: what needs to be considered when setting up a new repository, how to create a subfolder in a repository, etc.)

It is my feeling that the index page of the [Gitea documentation] is intended for a different audience (mostly admins) and does not serve the purpose well to guide new users.

Many thanks for considering this issue!

Screenshots

Originally created by @rk-mlu on GitHub (May 5, 2021). - Gitea version (or commit ref): 1.14.1 - Git version: 2.20.1 - Operating system: not relevant ## Description Dear Gitea developers, I am a member of an admin team which is responsible for running a Gitea instance to collaborate on projects on a department level at a university. In the wake of the pandemic our user base has increased considerably, and the use cases have developed far beyond our initial intentions to jointly develop code or to write LaTeX documents etc. While we are happy with this development, the increased number of inexperienced Git(-ea) users has also come with some additional obstacles. Many of our new users do not have any pre-existing experience with other Git environments such as GitHub, GitLab etc. While we are busy in teaching/training them how to use git and integrate it in their workflow, we also received several notifications that the help function of the web UI is often causing frustration, especially, for new users. For instance, if I click on my avatar in the upper right corner, I am offered a help button, which leads to the [Gitea documentation](https://docs.gitea.io/). As an admin, I am quite happy with these docs. However, these pages are not exactly what a first time Git/Gitea user is usually expecting. While we are, of course, offering internal training measures, I have the feeling that the user experience, especially for Git/Gitea newcomers, could be improved without much effort. My suggestion is: If I click on the 'Help' button as a standard user (it might be different for admins of course), I should be referred to a page which contains some rather basic information about Git and Gitea. For example: - One could mention, for instance, that Git and Gitea are actually two different things. - There should be a reference to free Git resources, e.g., the [Git book](https://git-scm.com/book/en/v2). It is perfectly fine, imho, that the Gitea community does not offer any user support on git itself, but the main help page may refer a new user to places where he or she finds some support. - A user (not admin) centric FAQ would also be appreciated with questions that are gitea-web-ui related (like: what needs to be considered when setting up a new repository, how to create a subfolder in a repository, etc.) It is my feeling that the index page of the [Gitea documentation] is intended for a different audience (mostly admins) and does not serve the purpose well to guide new users. Many thanks for considering this issue! ## Screenshots ![Screenshot](https://user-images.githubusercontent.com/65403623/117161048-e8be2180-adc1-11eb-8e4e-5bc6ceab179e.png)

GiteaMirror added the type/docs label 2025-11-02 07:22:22 -06:00

GiteaMirror closed this issue

2025-11-02 07:22:22 -06:00

GiteaMirror commented

2025-11-02 07:22:22 -06:00

@techknowlogick commented on GitHub (May 5, 2021):

https://docs.codeberg.org/ probably has some things that may be helpful to you

@techknowlogick commented on GitHub (May 5, 2021): https://docs.codeberg.org/ probably has some things that may be helpful to you

GiteaMirror commented

2025-11-02 07:22:23 -06:00

@rk-mlu commented on GitHub (May 5, 2021):

@techknowlogick Yes, exactly! Many thanks for the reference.

Another nice resource for git beginners is, for instance, oh-my-git.

It would be nice if the gitea default help page includes a small (reliable) collection of such external resources to get people started, who are not git/gitea experts yet.

@rk-mlu commented on GitHub (May 5, 2021): @techknowlogick Yes, exactly! Many thanks for the reference. Another nice resource for git beginners is, for instance, [oh-my-git](https://github.com/git-learning-game/oh-my-git). It would be nice if the gitea default help page includes a small (reliable) collection of such external resources to get people started, who are not git/gitea experts yet.

GiteaMirror commented

2025-11-02 07:22:23 -06:00

@fnetX commented on GitHub (Jun 14, 2021):

Hey there,

we at Codeberg are working on a documentation for end-users, and we are usually considering keeping it generic to Gitea as much as possible (Also, we don't touch Gitea core parts, but it might be worth a discussion if links to additional topics like Pages / CI or maybe disabled features are too confusing to end users).

What about officially linking to this resource as end-user guide for Gitea to save duplicated work?
Also, currently many help links in Gitea link to GitHub, and downstream discussed already to replace them, so we could also swap out the GitHub links to Codeberg ones for that matter.

We'll probably do the work anyway, the big question is if we should care about being more generic and landing it in Gitea, or targeting just Codeberg.

@fnetX commented on GitHub (Jun 14, 2021): Hey there, we at Codeberg are working on a documentation for end-users, and we are usually considering keeping it generic to Gitea as much as possible (Also, we don't touch Gitea core parts, but it might be worth a discussion if links to additional topics like Pages / CI or maybe disabled features are too confusing to end users). What about officially linking to this resource as end-user guide for Gitea to save duplicated work? Also, currently many help links in Gitea link to GitHub, and [downstream discussed already](https://codeberg.org/Codeberg/Community/issues/459) to replace them, so we could also swap out the GitHub links to Codeberg ones for that matter. We'll probably do the work anyway, [the big question](https://codeberg.org/Codeberg/Documentation/issues/134) is if we should care about being more generic and landing it in Gitea, or targeting just Codeberg.

GiteaMirror commented

2025-11-02 07:22:23 -06:00

@lunny commented on GitHub (Jun 15, 2021):

Thank you for your consideration. The end-user documentation is one of the important parts which Gitea missed. I think Gitea should build one and link to the official https://docs.gitea.io. And also the Gitea's documentation should have a similar style with current design.

@lunny commented on GitHub (Jun 15, 2021): Thank you for your consideration. The end-user documentation is one of the important parts which Gitea missed. I think Gitea should build one and link to the official https://docs.gitea.io. And also the Gitea's documentation should have a similar style with current design.

GiteaMirror commented

2025-11-02 07:22:23 -06:00

@fnetX commented on GitHub (Jun 15, 2021):

The point is: We're doing the work, you have an open issue. We can replace the links for now, which is better than linking to GitHub IMHO. You can still create your own docs if you feel the need later. Also, you can copy content from the Codeberg Docs once you are starting your work, it's CC-BY-SA.

@fnetX commented on GitHub (Jun 15, 2021): The point is: We're doing the work, you have an open issue. We can replace the links for now, which is better than linking to GitHub IMHO. You can still create your own docs if you feel the need later. Also, you can copy content from the Codeberg Docs once you are starting your work, it's CC-BY-SA.

GiteaMirror commented

2025-11-02 07:22:23 -06:00

@noerw commented on GitHub (Sep 13, 2022):

docs.codeberg.org is really valueable ❤️

I think having these docs bundled with each gitea install would be a good way to go about this. Then instances can customize the content via templates & have it themed as the gitea instance itself, and linking to docs from the web-UI wouldn't risk broken links as much.

My only doubt about this is the increased maintenance burden with keeping these docs up to date. The current gitea admin docs are under-maintained already -- I'm not sure the gitea project currently could maintain quality for even more docs. This would require either a shift of attitude wrt documentation by the current maintainers, or new maintainers for those docs (I'd be up for it, but only have time occasionally so can't pull it off alone)

Further thoughts:

Templates for this content should be designed with extensibility in mind.
In the long run, codeberg docs could be switched over to use the builtin docs, extended with docs for their own offerings — stopping the current praxis of outsourcing the documentation maintenance burden to codeberg. @fnetX what do you think? I assume you want to avoid having docs in multiple places (i.e. generic gitea docs here and your custom docs there)?

For a practical example, assuming a similar layout as the current docs.codeberg.org site: There would be a $custom/templates/docs/sidebar.tmpl that includes a $custom/templates/docs/sidebar_local.tmpl (or similar) at the bottom, which could be used to include other templates, avoiding the need to diff changes to the main template when updating gitea.
It would be useful if custom doc content was authored in markdown instead of go-template syntax (for reusability with static site generators, or gitea / github rendering). Having markdown source would mean that this content can't live in $custom/templates/docs/*.tmpl, but in [docs] CUSTOM_DIR. If that dir is set to be a checkout of a gitea repo, this would even enable the workflow of managing docs content within the gitea instance itself.<
Maybe the latter part is a bit too complicated for a use case very few orgs would use.

@noerw commented on GitHub (Sep 13, 2022): docs.codeberg.org is really valueable :heart: I think having these docs bundled with each gitea install would be a good way to go about this. Then instances can customize the content via templates & have it themed as the gitea instance itself, and linking to docs from the web-UI wouldn't risk broken links as much. My only doubt about this is the increased maintenance burden with keeping these docs up to date. The current gitea admin docs are under-maintained already -- I'm not sure the gitea project currently could maintain quality for even more docs. This would require either a shift of attitude wrt documentation by the current maintainers, or new maintainers for those docs (I'd be up for it, but only have time occasionally so can't pull it off alone) --- Further thoughts: 1. Templates for this content should be designed with **extensibility** in mind. In the long run, codeberg docs could be switched over to use the builtin docs, extended with docs for their own offerings — stopping the current praxis of outsourcing the documentation maintenance burden to codeberg. @fnetX what do you think? I assume you want to avoid having docs in multiple places (i.e. generic gitea docs here and your custom docs there)? For a practical **example**, assuming a similar layout as the current docs.codeberg.org site: There would be a `$custom/templates/docs/sidebar.tmpl` that includes a `$custom/templates/docs/sidebar_local.tmpl` (or similar) at the bottom, which could be used to include other templates, avoiding the need to diff changes to the main template when updating gitea. 2. It would be useful if custom doc content was authored in **markdown** instead of go-template syntax (for reusability with static site generators, or gitea / github rendering). Having markdown source would mean that this content can't live in `$custom/templates/docs/*.tmpl`, but in `[docs] CUSTOM_DIR`. If that dir is set to be a checkout of a gitea repo, this would even enable the workflow of managing docs content within the gitea instance itself.< Maybe the latter part is a bit too complicated for a use case very few orgs would use.

GiteaMirror commented

2025-11-02 07:22:23 -06:00

@fnetX commented on GitHub (Oct 5, 2022):

@noerw thank you for the comment, I agree. I read it in my emails earlier and wanted to reply quicker, but I was logged out of GitHub and too lazy to sign in again (I only use it for the Gitea issue tracker, so ...)

+1 also for bundling the docs with each Gitea installation, links within Gitea could point to the internal URL, solving privacy issues as well as confusion for end users about which version to look for.

At Codeberg, we're somewhat familiar with Gitea itself. If our official "deployment" of the docs is a patch to our Gitea fork, it should be somewhat easy to sync them back to Gitea from time to time. Since we're already taking the efforts, I'm all for merging this. And we wouldn't need to maintain our own generator any more.

Let me think about some practical approaches to this, but count me in. I somehow propose to store the docs in a separate repo and pull them in while building Gitea, if this is possible. I think that Gitea maintenance is already too busy. It could indeed be outsourced to a few independent people (e.g. even non-coders) to maintain the docs, and only connect before a release to ensure the docs are up2date.

@fnetX commented on GitHub (Oct 5, 2022): @noerw thank you for the comment, I agree. I read it in my emails earlier and wanted to reply quicker, but I was logged out of GitHub and too lazy to sign in again (I only use it for the Gitea issue tracker, so ...) +1 also for bundling the docs with each Gitea installation, links within Gitea could point to the internal URL, solving privacy issues as well as confusion for end users about which version to look for. At Codeberg, we're somewhat familiar with Gitea itself. If our official "deployment" of the docs is a patch to our Gitea fork, it should be somewhat easy to sync them back to Gitea from time to time. Since we're already taking the efforts, I'm all for merging this. And we wouldn't need to maintain our own generator any more. Let me think about some practical approaches to this, but count me in. I somehow propose to store the docs in a separate repo and pull them in while building Gitea, if this is possible. I think that Gitea maintenance is already too busy. It could indeed be outsourced to a few independent people (e.g. even non-coders) to maintain the docs, and only connect before a release to ensure the docs are up2date.

GiteaMirror commented

2025-11-02 07:22:23 -06:00

@fnetX commented on GitHub (Nov 5, 2022):

Hello everyone,

during the Codeberg hackathon these days, we're taking the effort to try and upstream our documentation.

This means:

we are implementing a package that can be depended on by upstream Gitea to include the docs
the docs are included within each instance's build and served there to match the current version
this might mean changes to the licensing of our docs to meet yours (Apache 2.0 license)

The effort can be followed in: https://codeberg.org/Codeberg/Gitea-Documentation/

@fnetX commented on GitHub (Nov 5, 2022): Hello everyone, during the Codeberg hackathon these days, we're taking the effort to try and upstream our documentation. This means: - we are implementing a package that can be depended on by upstream Gitea to include the docs - the docs are included within each instance's build and served there to match the current version - this might mean changes to the licensing of our docs to meet yours (Apache 2.0 license) The effort can be followed in: https://codeberg.org/Codeberg/Gitea-Documentation/

GiteaMirror commented

2025-11-02 07:22:24 -06:00

@lunny commented on GitHub (May 25, 2023):

Since now the new documentations splited administration and usage. I think we can close this and PRs are welcome for end users under usage.

@lunny commented on GitHub (May 25, 2023): Since now the new documentations splited `administration` and `usage`. I think we can close this and PRs are welcome for end users under `usage`.

Sign in to join this conversation.

Branches Tags

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: github-starred/gitea#7297