Claim of completeness vs. external resources #134

fnetX commented 2021年06月02日 13:04:29 +02:00

Hey,

do we want to have a complete git-Gitea-workflow covering documentation along with Codeberg (because we're growing and serving as a well-known resource), or is it okay to just include external articles?

I mean, it sounds kinda inefficient to rewrite everything for Codeberg, even if it is already written in the Git, Gitea, GitHub, GitLab or in hundreds of blog articles around the web.

What do you think? Maybe just write some stubs for important topics and link to external resources?

Hey, do we want to have a complete git-Gitea-workflow covering documentation along with Codeberg (because we're growing and serving as a well-known resource), or is it okay to just include external articles? I mean, it sounds kinda inefficient to rewrite everything for Codeberg, even if it is already written in the Git, Gitea, GitHub, GitLab or in hundreds of blog articles around the web. What do you think? Maybe just write some stubs for important topics and link to external resources?

fnetX commented 2021年06月02日 13:16:22 +02:00

related: #459, we could have a look at the URLs and see what's missing, then decide if we want it in our own docs or link to some other resources.

With @n I already discussed if even want to copy parts of documentations that are CC-BY licenced.

related: #459, we could have a look at the URLs and see what's missing, then decide if we want it in our own docs or link to some other resources. With @n I already discussed if even want to copy parts of documentations that are CC-BY licenced.

Ghost commented 2021年06月02日 19:26:43 +02:00

I think the most important thing is that we describe the topics that are codeberg-specific - because we deviate from the Gitea standard or because they are own functions like pages.

For the standard Gitea functions, linking to the upstream doc seems fine. We may eventually replace this by own docs if need be, but this doesn't seem a priority task.

Linking to external resources, especially on services we'd like to replace or atleast compete with (GitHub) doesn't feel "right" to me.

Maybe we can introduce some labels to flag issues that should be handled with priority?

I think the most important thing is that we describe the topics that are codeberg-specific - because we deviate from the Gitea standard or because they are own functions like pages. For the standard Gitea functions, linking to the upstream doc seems fine. We may eventually replace this by own docs if need be, but this doesn't seem a priority task. Linking to external resources, especially on services we'd like to replace or atleast compete with (GitHub) doesn't feel "right" to me. Maybe we can introduce some labels to flag issues that should be handled with priority?

fnetX commented 2021年06月03日 18:31:03 +02:00

Relevant: #135

In worst case we could add stubs and link somewhere else, maybe with some tl;dr notes or codeberg-specific annotations.

Relevant: #135 In worst case we could add stubs and link somewhere else, maybe with some tl;dr notes or codeberg-specific annotations.

n commented 2021年06月04日 12:20:09 +02:00

It would certainly depend on the type of content. We shouldn't link to StackExchange or blog posts, where the instructions may be not well organized or specific to a certain problem.

However, we can link to general guides (like for Git or Markdown) where we wouldn't gain anything by writing an article ourselves, or the work needed would be substantial.
For example, https://git-rebase.io/ and https://commonmark.org/help/.

It would certainly depend on the type of content. We shouldn't link to StackExchange or blog posts, where the instructions may be not well organized or specific to a certain problem. However, we can link to general guides (like for Git or Markdown) where we wouldn't gain anything by writing an article ourselves, or the work needed would be substantial. For example, https://git-rebase.io/ and https://commonmark.org/help/.

n commented 2021年06月04日 12:21:15 +02:00

For the standard Gitea functions, linking to the upstream doc seems fine. We may eventually replace this by own docs if need be, but this doesn't seem a priority task.

The Gitea docs is targeted at admins, not at end users. So generally this isn't something we can link to.

> For the standard Gitea functions, linking to the upstream doc seems fine. We may eventually replace this by own docs if need be, but this doesn't seem a priority task. The Gitea docs is targeted at admins, not at end users. So generally this isn't something we can link to.

fnetX commented 2021年06月04日 12:25:58 +02:00

We shouldn't link to StackExchange or blog posts

I agree to the first, we should pick resources that are kept up-to-date, but certain blog posts are surely eligible. Or do you just mean that we should not link to resources where the information is not well organized?

The Gitea docs is targeted at admins, not at end users

I found the "Usage" section quite useful at times, but I agree, it's sometimes a bit distracting with the technical bits of how to enable / disable this certain feature in your instance etc.
We could also reach out to upstream and ask if we should combine the efforts for an end-user manual. Since they currently link to GitHub even from the GUI, they might also be open to replacing those links with our Codeberg documentation, that should be up-to-date with the Gitea versions + eventually be a good alternative to the GitHub one?

> We shouldn't link to StackExchange or blog posts I agree to the first, we should pick resources that are kept up-to-date, but certain blog posts are surely eligible. Or do you just mean that we should not link to resources where the information is not well organized? > The Gitea docs is targeted at admins, not at end users I found the "Usage" section quite useful at times, but I agree, it's sometimes a bit distracting with the technical bits of how to enable / disable this certain feature in your instance etc. We could also reach out to upstream and ask if we should combine the efforts for an end-user manual. Since they currently link to GitHub even from the GUI, they might also be open to replacing those links with our Codeberg documentation, that should be up-to-date with the Gitea versions + eventually be a good alternative to the GitHub one?

n commented 2021年06月04日 13:24:34 +02:00

In general, here are some questions we can ask before we link anything (including blog posts):

• Is the content accessible to readers?
• Is the content of appropriate quality?
• Will it be relevant/updated in a year?

---

I like the idea for working with Gitea for a user manual. Here's a relevant upstream issue: go-gitea/gitea#15736

In general, here are some questions we can ask before we link anything (including blog posts): - Is the content accessible to readers? - Is the content of appropriate quality? - Will it be relevant/updated in a year? --- I like the idea for working with Gitea for a user manual. Here's a relevant upstream issue: [go-gitea/gitea#15736](https://github.com/go-gitea/gitea/issues/15736)

n commented 2021年06月07日 10:37:53 +02:00

For attribution of external works, here's what I suggested to add to the end of an guide in #127:

---
> **Attribution** 
> This guide is derived from [GitHub Docs](https://docs.github.com), used under CC-BY 4.0.

Suggestions are welcome, and we can extend this using a custom style in the future.

For attribution of external works, here's what I suggested to add to the end of an guide in #127: ```markdown --- > **Attribution** > This guide is derived from [GitHub Docs](https://docs.github.com), used under CC-BY 4.0. ``` Suggestions are welcome, and we can extend this using a custom style in the future.

fnetX commented 2021年06月14日 15:48:57 +02:00

I like the idea for working with Gitea for a user manual

I just commented on the issue. Thank you for the pointer.

> I like the idea for working with Gitea for a user manual I just commented on the issue. Thank you for the pointer.