Claim of completeness vs. external resources #134

Open
opened 5 months ago by fnetX · 9 comments
fnetX commented 5 months ago
Collaborator

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 added the
Status: Needs feedback
Kind: Question
Kind: Documentation
labels 5 months ago
Poster
Collaborator

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.
Collaborator

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?
Poster
Collaborator

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 5 months ago
Collaborator

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 5 months ago
Collaborator

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.
Poster
Collaborator

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 5 months ago
Collaborator

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 5 months ago
Collaborator

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.
Poster
Collaborator

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.
Sign in to join this conversation.
No Milestone
No Assignees
3 Participants
Notifications
Due Date

No due date set.

Dependencies

This issue currently doesn't have any dependencies.

Loading…
There is no content yet.