Getting Started Guide #47

Merged
n merged 6 commits from :getting-started into master 2 years ago

Closes #26

The basics of issue tracking as well as the basics of contributing to wikis are still missing, hence this is still WIP.

Feedback on tone and overall idea is warmly welcome :)

Closes #26 The basics of issue tracking as well as the basics of contributing to wikis are still missing, hence this is still WIP. Feedback on tone and overall idea is warmly welcome :)
lhinderberger added the
Status: In progress
Kind: Documentation
labels 2 years ago
Poster

I have decided to not write an article about the basics of contributing to a wiki right now, as I have no experience with Gitea wikis so far. Maybe someone might want to contribute. But I don't think that wiki basics are critical enough to block the rest of the guide.

So, this is ready for review now :)

I have decided to not write an article about the basics of contributing to a wiki right now, as I have no experience with Gitea wikis so far. Maybe someone might want to contribute. But I don't think that wiki basics are critical enough to block the rest of the guide. So, this is ready for review now :)
lhinderberger added
Status: Ready for Review
and removed
Status: In progress
labels 2 years ago
lhinderberger changed title from WIP: Getting Started Guide to Getting Started Guide 2 years ago
hw commented 2 years ago
Owner

nice! @n -- would you like to review+merge+deploy?

nice! @n -- would you like to review+merge+deploy?
Poster

By the way, I have created accounts for "Knut" on both codeberg-test and codeberg now, just so that noone tries to register to our documentation's test user, trolling people or the like 😄

If we decide to keep Knut as our documentation "mascot" and demo account (much like GitHub's octocat account), I could provide access to the accounts to Documentation contributors (if allowed and possible). We'd need a safe way to do so though.

By the way, I have created accounts for "Knut" on both codeberg-test and codeberg now, just so that noone tries to register to our documentation's test user, trolling people or the like :smile: If we decide to keep Knut as our documentation "mascot" and demo account (much like [GitHub's octocat account](https://github.com/octocat)), I could provide access to the accounts to Documentation contributors (if allowed and possible). We'd need a safe way to do so though.
hw commented 2 years ago
Owner

If we decide to keep Knut as our documentation "mascot" and demo account (much like GitHub's octocat), [...]

There has been a trade mark debate around the Berlin Zoo, if you have some time maybe check the EUIPO database to be sure

> If we decide to keep Knut as our documentation "mascot" and demo account (much like [GitHub's octocat](https://github.com/octocat)), [...] There has been a trade mark debate around the Berlin Zoo, if you have some time maybe check the EUIPO database to be sure
Poster

Thanks for the heads up - I really didn't expect yet another legal landmine there!
Am I the only one who thinks it's a bit weird to trademark a real animal? 😅

But oh well, DPMA Register yields only non-active/revoked/rejected/deleted trademarks for "Knut Eisbär" and a search for "Knut" brought up no active trademarks that match our use of the name Knut AND be in the same Nizza class, in my layman opinion.

Thanks for the heads up - I really didn't expect yet another legal landmine there! Am I the only one who thinks it's a bit weird to trademark a real animal? :sweat_smile: But oh well, DPMA Register yields only non-active/revoked/rejected/deleted trademarks for "Knut Eisbär" and a search for "Knut" brought up no active trademarks that match our use of the name Knut AND be in the same Nizza class, in my layman opinion.
Poster

Another small investigation into this reveals that protection of the various Knut der Eisbär brands appears to have expired on or around 2017.

Additionally, I couldn't find the brand "Knut" on the website of the Berlin Zoo. There are some mentions of him in various articles, but I couldn't find any Knut products being sold there. There are various Knut-branded articles on Amazon, though they seem to be either not "official" or old-stock and so far I couldnt find one having to do with software or education.

Based on this information I as a layman think that the formely registered Knut brand is expired and will not collide with our use of the name Knut.

Nevertheless, I think we can come up with a better, more unique name than Knut. The more I think about the name Knut, the less appropriate I think it is to use that name for our mascot, given that it is name of a dead animal (even if it was famous once). It also might be hard to pronounce for English speakers.

So I think we could in principle merge this under the working title "Knut" but open a new issue in /Community or /Design looking for a proper mascot :)

Another small investigation into this reveals that protection of the various Knut der Eisbär brands appears to have expired on or around 2017. Additionally, I couldn't find the brand "Knut" on the website of the Berlin Zoo. There are some mentions of him in various articles, but I couldn't find any Knut products being sold there. There are various Knut-branded articles on Amazon, though they seem to be either not "official" or old-stock and so far I couldnt find one having to do with software or education. Based on this information I as a layman think that the formely registered Knut brand is expired and will not collide with our use of the name Knut. Nevertheless, I think we can come up with a better, more unique name than Knut. The more I think about the name Knut, the less appropriate I think it is to use that name for our mascot, given that it is name of a dead animal (even if it was famous once). It also might be hard to pronounce for English speakers. So I think we could in principle merge this under the working title "Knut" but open a new issue in /Community or /Design looking for a proper mascot :)
n requested changes 2 years ago
n left a comment
Collaborator

Really nice, except for some minor issues. 🙂

I especially like the idea of a mascot!

Really nice, except for some minor issues. 🙂 I especially like the idea of a mascot!
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
n commented 2 years ago
Collaborator
We can minify the image: https://paste.sr.ht/blob/72a7fd0d677b63ca45ebf4a866eb44d0ba71befb
Poster

With gzip encoding already being enabled in docs.codeberg.org, how much would we save?

With gzip encoding already being enabled in docs.codeberg.org, how much would we save?
n commented 2 years ago
Collaborator
❯ du -b *
5612	knut.svg
1894	knut-minified.svg

❯ du -b *
2084	knut.svg.gz
820	knut-minified.svg.gz

We'd save about 1.3kB.

``` ❯ du -b * 5612 knut.svg 1894 knut-minified.svg ❯ du -b * 2084 knut.svg.gz 820 knut-minified.svg.gz ``` We'd save about 1.3kB.
Poster

Okay, that is indeed significant. I will have a look at it in the evening. Thanks! :)

Okay, that is indeed significant. I will have a look at it in the evening. Thanks! :)
lhinderberger marked this conversation as resolved
---
## Registering at Codeberg.org
![Register](/assets/images/getting-started/first-steps/register.webp)
n commented 2 years ago
Collaborator

We should avoid using WebP for now, since Safari does not render it yet (Gitea has support for Safari).
https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types

We should avoid using WebP for now, since Safari does not render it yet ([Gitea has support for Safari](https://docs.gitea.io/en-us/#browser-support)). https://developer.mozilla.org/en-US/docs/Web/Media/Formats/Image_types
Poster

Safari 14 will support WebP, according to the release notes of the beta.

Does Safari auto-update? In that case, I think it would be okay to just wait and let time solve this problem, because if the Beta is out now, the final release can't be too far out.

The alternative would be to replace everything with png/jpeg, have much larger file sizes and thus much more traffic for the majority of our users.

Safari 14 will support WebP, according to the release notes of the beta. Does Safari auto-update? In that case, I think it would be okay to just wait and let time solve this problem, because if the Beta is out now, the final release can't be too far out. The alternative would be to replace everything with png/jpeg, have much larger file sizes and thus much more traffic for the majority of our users.
n commented 2 years ago
Collaborator

With Safari, updates are bundled with the OS. People would have to update to iOS 14 and macOS Big Sur before they can see WebP images.

With Safari, [updates are bundled](https://support.apple.com/en-us/HT204416) with the OS. People would have to update to iOS 14 and macOS Big Sur before they can see WebP images.
Poster

I feel very reluctant to change all the images on the site just because of Apple not keeping up. But I guess we have no choice, unless we want to exclude Mac and iPhone users, of which there are many.

In that case I will also have to change out the screenshots (and photo) of my 2FA guide. That will take some time, I can have a look at it in the evening.

Thanks for letting me know about that potential caveat! :)

I feel very reluctant to change all the images on the site just because of Apple not keeping up. But I guess we have no choice, unless we want to exclude Mac and iPhone users, of which there are many. In that case I will also have to change out the screenshots (and photo) of my 2FA guide. That will take some time, I can have a look at it in the evening. Thanks for letting me know about that potential caveat! :)
## Orienting yourself on Codeberg
After successfully registering on Codeberg, you should see this screen:
![Dashboard](/assets/images/getting-started/first-steps/dashboard.webp)
n commented 2 years ago
Collaborator

The red circles don't look very good. Perhaps we can use zoom and blur effects to draw focus instead, similar to how GitHub's guide does.

The red circles don't look very good. Perhaps we can use zoom and blur effects to draw focus instead, similar to [how GitHub's guide](https://guides.github.com/features/pages/) does.
Poster

Agreed, but let's change that with a separate PR, because then we'd unify image highlighting everywhere on Codeberg Documentation, not just in the Getting Started Guide.

Right now, I'd say we take it how it is, because changing the highlighting would be quite time-consuming and it's probably better to have a slightly imperfect guide than none at all.

Agreed, but let's change that with a separate PR, because then we'd unify image highlighting everywhere on Codeberg Documentation, not just in the Getting Started Guide. Right now, I'd say we take it how it is, because changing the highlighting would be quite time-consuming and it's probably better to have a slightly imperfect guide than none at all.
n commented 2 years ago
Collaborator

Agreed!

Agreed!
Poster

Great, #52 will track the issue.

Great, #52 will track the issue.
lhinderberger marked this conversation as resolved
- **Dashboard (1)** is the screen you're looking at right now. It gives you an overview of the newest activity
of you, the people you follow and in your or your organization's projects.
- **Issues (2)** and **Pull Requests (3)** These are overviews over issues and pull requests that you are either involved in or that are part of one of the organizations you belong to.
n commented 2 years ago
Collaborator

These are overviews over issues..

Overviews of would sound better here.

> These are overviews over issues.. Overviews **of** would sound better here.
Poster

Do you mean "overviews of issues and pull requests"?

Do you mean "overviews of issues and pull requests"?
Poster

Sorry, missed your quote above - I'll fix it 👍

Sorry, missed your quote above - I'll fix it 👍
lhinderberger marked this conversation as resolved
- **Dashboard (1)** is the screen you're looking at right now. It gives you an overview of the newest activity
of you, the people you follow and in your or your organization's projects.
- **Issues (2)** and **Pull Requests (3)** These are overviews over issues and pull requests that you are either involved in or that are part of one of the organizations you belong to.
- **Codeberg Issues (4)** This is currently the prime communication channel withing the Codeberg Community. Here, you can ask questions, report bugs and suggest changes to Codeberg. You're also welcome to browse these issues and contribute your solutions, if you want to support Codeberg even more.
n commented 2 years ago
Collaborator

prime

You might mean primary. 🙂

within

I think for might better suit the context.

> prime You might mean `primary`. 🙂️ > within I think `for` might better suit the context.
Poster

Agreed, will change :)

Agreed, will change :)
lhinderberger marked this conversation as resolved
#### Be (reasonably) patient
Please remember that many project maintainers work on their free software projects
in their free time. Some maintainers may answer you within minutes, others within days.
Don't be discouraged if there won't be an immediate answer.
n commented 2 years ago
Collaborator

suggestion: won't be --> isn't

suggestion: `won't be` --> `isn't`
Poster

👍

👍
lhinderberger marked this conversation as resolved
Codeberg is a community-driven, non-profit software development platform operated
by Codeberg e.V. and centered around Codeberg.org, a Gitea-based software forge.
On Codeberg you can develop your own Free Software projects, contribute to other
n commented 2 years ago
Collaborator

We could link to an article here describing what free software is for those who don't know. Perhaps the article on the Simple English Wikipedia will suffice?

We could link to an article here describing what free software is for those who don't know. Perhaps [the article on the Simple English Wikipedia](https://simple.wikipedia.org/wiki/Free_software) will suffice?
Poster

Absolutely! 👍

Absolutely! 👍
lhinderberger marked this conversation as resolved
Poster

Thank you for your comments! 👍

I will incorporate the changes into the PR (except for the SVG and WEBP thing, let's discuss that above).

I'm glad you like the mascot idea 😊 I was a bit worried at first about whether a mascot will resonate well.

Thank you for your comments! 👍 I will incorporate the changes into the PR (except for the SVG and WEBP thing, let's discuss that above). I'm glad you like the mascot idea 😊 I was a bit worried at first about whether a mascot will resonate well.
Poster

I added an optimized version of Knut and I found a way to provide a fallback for browsers that don't support webp while giving all other browsers the advantages of webp using the picture tag.

Fallback for 2FA article is already merged to master.

@n - please feel free to merge, unless something else needs to be improved/fixed! :)

I added an optimized version of Knut and I found a way to provide a fallback for browsers that don't support webp while giving all other browsers the advantages of webp using the `picture` tag. Fallback for 2FA article is already merged to master. @n - please feel free to merge, unless something else needs to be improved/fixed! :)
n approved these changes 2 years ago
n merged commit ecc47f425c into master 2 years ago
n commented 2 years ago
Collaborator

It's live!

It's live!
Poster

Thank you! :)

Thank you! :)
lhinderberger deleted branch getting-started 2 years ago

Reviewers

n approved these changes 2 years ago
The pull request has been merged as ecc47f425c.
Sign in to join this conversation.
No reviewers
No Milestone
No Assignees
3 Participants
Notifications
Due Date

No due date set.

Dependencies

This pull request currently doesn't have any dependencies.

Loading…
There is no content yet.