What parts of our web interface need further documentation? #67

Closed
opened 2 years ago by lhinderberger · 32 comments

In #64, the question was brought up which parts of Codeberg's web interface need further documentation.

@ivan-paleo suggested documenting the Git-related parts of the web interface in greater detail.

It would be great to collect a list of web workflows that need to be documented in this issue.

In #64, the question was brought up which parts of Codeberg's web interface need further documentation. @ivan-paleo suggested documenting the Git-related parts of the web interface in greater detail. It would be great to collect a list of web workflows that need to be documented in this issue.
lhinderberger added the
Status: Needs feedback
Kind: Documentation
labels 2 years ago

Import of repos: see Documentation #35 and Community #250.

I wouldn't mind writing (some of) the text, but for that I would need to know in which format and what I need to document. Depending on the format, I might not be able to insert it into the documentation myself.

Import of repos: see Documentation [#35](https://codeberg.org/Codeberg/Documentation/issues/35) and Community [#250](https://codeberg.org/Codeberg/Community/issues/250). I wouldn't mind writing (some of) the text, but for that I would need to know in which format and what I need to document. Depending on the format, I might not be able to insert it into the documentation myself.

I don't think I can link issues, but #56 is related to it too, right?

I don't think I can link issues, but [#56](https://codeberg.org/Codeberg/Documentation/issues/56) is related to it too, right?

@ivan-paleo It's always great to see new contributors to Codeberg Documentation - Welcome! :) The articles can be found in the content directory of this repository. They're written in Markdown. To contribute, please fork the repository, commit your contributions to your fork and open a Pull Request.

Can you please explain what you mean with link issues? :) In theory it should be possible to refer to any issue from any other issue - if both issues are in the same repository, it's enough to refer to them by their issue number (EDIT: the link will then be inserted automatically). If they're in different repos, you'll need to prefix the repository's "path", like for example Codeberg/Community#250

@ivan-paleo It's always great to see new contributors to Codeberg Documentation - Welcome! :) The articles can be found in the `content` directory of this repository. They're written in Markdown. To contribute, please fork the repository, commit your contributions to your fork and open a Pull Request. Can you please explain what you mean with link issues? :) In theory it should be possible to refer to any issue from any other issue - if both issues are in the same repository, it's enough to refer to them by their issue number (EDIT: the link will then be inserted automatically). If they're in different repos, you'll need to prefix the repository's "path", like for example Codeberg/Community#250

@ivan-paleo It's always great to see new contributors to Codeberg Documentation - Welcome! :) The articles can be found in the content directory of this repository. They're written in Markdown. To contribute, please fork the repository, commit your contributions to your fork and open a Pull Request.

I'll try to do that then; I should be able to write in Markdown :)

Can you please explain what you mean with link issues? :) In theory it should be possible to refer to any issue from any other issue - if both issues are in the same repository, it's enough to refer to them by their issue number (EDIT: the link will then be inserted automatically). If they're in different repos, you'll need to prefix the repository's "path", like for example Codeberg/Community#250

What I meant is not just about adding the link to an issue in a comment, but rather truly link issues like you did (see screenshot).
EDIT: OK, I've just noticed this referencing is automatic, nice!

> @ivan-paleo It's always great to see new contributors to Codeberg Documentation - Welcome! :) The articles can be found in the `content` directory of this repository. They're written in Markdown. To contribute, please fork the repository, commit your contributions to your fork and open a Pull Request. I'll try to do that then; I should be able to write in Markdown :) > Can you please explain what you mean with link issues? :) In theory it should be possible to refer to any issue from any other issue - if both issues are in the same repository, it's enough to refer to them by their issue number (EDIT: the link will then be inserted automatically). If they're in different repos, you'll need to prefix the repository's "path", like for example Codeberg/Community#250 What I meant is not just about adding the link to an issue in a comment, but rather truly link issues like you did (see screenshot). EDIT: OK, I've just noticed this referencing is automatic, nice!

@lhinderberger How do I insert screenshots in the documentation:

  • where should the file(s) be saved? Is it in assets/images? Should I create a folder there?
  • what format?
  • what (minimum) size?

Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"?

@lhinderberger How do I insert screenshots in the documentation: * where should the file(s) be saved? Is it in assets/images? Should I create a folder there? * what format? * what (minimum) size? Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"?

Regarding the import of repos, I think it should wait a bit, see #250

Regarding the import of repos, I think it should wait a bit, see [#250](https://codeberg.org/Codeberg/Community/issues/250)

EDIT: OK, I've just noticed this referencing is automatic, nice!

Yes that's right :) Only creating an issue dependency (so, a "hard" dependency of one issue blocking another) requires write permissions to a repository.

> EDIT: OK, I've just noticed this referencing is automatic, nice! Yes that's right :) Only creating an issue dependency (so, a "hard" dependency of one issue blocking another) requires write permissions to a repository.

@lhinderberger How do I insert screenshots in the documentation:

  • where should the file(s) be saved? Is it in assets/images? Should I create a folder there?

Yes, assets/images is the right place for screenshots. Make sure to put them in a directory that matches the path of the article (just like the existing screenshots), to keep a uniform structure. But if they end up in the wrong place, that wouldn't be the end of the world, as it would be fixed when reviewing the PR. :)

  • what format?
    Screenshots should be in the PNG format, as its lossless and does not have artifacts on geometric shapes.

Optionally, if you want it to be extra nice, feel free to also add a webp version (please use the -lossless option), embedding it using <picture> tags for smooth fallback on Safari (as seen here for example).
That would be super nice, but it's not required.

  • what (minimum) size?

It should be large enough that all relevant text can still be recognized. In practice, I have often used a resolution of about 1300x800px

Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"?

Creating a new branch is good practise for PRs, because it makes it easier to work on multiple articles in parallel (for example because one article cannot be pulled yet and you want to start to write the next one).

If you have any further questions, feel free to ask any time! :)

> @lhinderberger How do I insert screenshots in the documentation: > * where should the file(s) be saved? Is it in assets/images? Should I create a folder there? Yes, `assets/images` is the right place for screenshots. Make sure to put them in a directory that matches the path of the article (just like the existing screenshots), to keep a uniform structure. But if they end up in the wrong place, that wouldn't be the end of the world, as it would be fixed when reviewing the PR. :) > * what format? Screenshots should be in the PNG format, as its lossless and does not have artifacts on geometric shapes. **Optionally**, if you want it to be extra nice, feel free to also add a webp version (please use the `-lossless` option), embedding it using `<picture>` tags for smooth fallback on Safari ([as seen here for example](https://codeberg.org/Codeberg/Documentation/raw/branch/master/content/getting-started/issue-tracking-basics.md)). That would be super nice, but it's not required. > * what (minimum) size? It should be large enough that all relevant text can still be recognized. In practice, I have often used a resolution of about 1300x800px > Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"? Creating a new branch is good practise for PRs, because it makes it easier to work on multiple articles in parallel (for example because one article cannot be pulled yet and you want to start to write the next one). If you have any further questions, feel free to ask any time! :)

I have specified the links like this
![](/assets/images/clone-commit-via-http/file.png)
but I don't see the images in the preview. I checked your markdown files and they don't show the preview either. Is that normal?

I have specified the links like this `![](/assets/images/clone-commit-via-http/file.png)` but I don't see the images in the preview. I checked your markdown files and they don't show the preview either. Is that normal?
  • what (minimum) size?

It should be large enough that all relevant text can still be recognized. In practice, I have often used a resolution of about 1300x800px

Some of them are smaller, so I might have to specify the dimensions of the image.

Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"?

Creating a new branch is good practise for PRs, because it makes it easier to work on multiple articles in parallel (for example because one article cannot be pulled yet and you want to start to write the next one).

I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch of the Codeberg repo? Alternatively, I could duplicate my Master branch to another one and PR from that new branch, right?

> > * what (minimum) size? > > It should be large enough that all relevant text can still be recognized. In practice, I have often used a resolution of about 1300x800px Some of them are smaller, so I might have to specify the dimensions of the image. > > > Should I commit to (my) master branch, or should I "create a new branch from this commit and start a pull request"? > > Creating a new branch is good practise for PRs, because it makes it easier to work on multiple articles in parallel (for example because one article cannot be pulled yet and you want to start to write the next one). I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch of the Codeberg repo? Alternatively, I could duplicate my Master branch to another one and PR from that new branch, right?

Are you editing the documentation using the web interface or do you use a local editor and the npm run serve command?

In the latter case, that sounds like a bug that needs further investigation.

The former case seems to be the same problem as in Codeberg/Community#252 - I think it would be worth the effort to reopen that issue with the goal of modifying Gitea to parse URLs starting with a slash as relative to the repository and not as relative to the web root.

Are you editing the documentation using the web interface or do you use a local editor and the `npm run serve` command? In the latter case, that sounds like a bug that needs further investigation. The former case seems to be the same problem as in Codeberg/Community#252 - I think it would be worth the effort to reopen that issue with the goal of modifying Gitea to parse URLs starting with a slash as relative to the repository and not as relative to the web root.

Are you editing the documentation using the web interface or do you use a local editor and the npm run serve command?

I've been using the web interface as I don't have a good editor for md files.

But if I specified the path to the images correctly, then I'm OK with not rendering correctly. Or should I specify the whole path? I tried with ./ and without leading slah as well, but no difference.

> Are you editing the documentation using the web interface or do you use a local editor and the `npm run serve` command? I've been using the web interface as I don't have a good editor for md files. But if I specified the path to the images correctly, then I'm OK with not rendering correctly. Or should I specify the whole path? I tried with `./` and without leading slah as well, but no difference.

I can warmly recommend Visual Studio Code (or VSCodium) for working on Codeberg Documentation - it's intuitive to use, great for Markdown and as a bonus it's a pleasure to look at. 😉

I can warmly recommend Visual Studio Code (or VSCodium) for working on Codeberg Documentation - it's intuitive to use, great for Markdown and as a bonus it's a pleasure to look at. :wink:

I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch [...]

This StackOverflow question seems to be the solution, if I understood your question correctly :)

> I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch [...] [This StackOverflow question](https://stackoverflow.com/questions/1628563/move-the-most-recent-commits-to-a-new-branch-with-git) seems to be the solution, if I understood your question correctly :)

I can warmly recommend Visual Studio Code (or VSCodium) for working on Codeberg Documentation - it's intuitive to use, great for Markdown and as a bonus it's a pleasure to look at. 😉

If I can connect it easily to Git/Codeberg, then I will try that :)

> I can warmly recommend Visual Studio Code (or VSCodium) for working on Codeberg Documentation - it's intuitive to use, great for Markdown and as a bonus it's a pleasure to look at. :wink: If I can connect it easily to Git/Codeberg, then I will try that :)

It has integrated Git support which makes it possible to clone your repo and make commits, pushes and pulls directly from within the editor. Alternatively, if you already have your repository cloned, you can simply point VS Code to the repository's directory and it should work out-of-the-box.

It has integrated Git support which makes it possible to clone your repo and make commits, pushes and pulls directly from within the editor. Alternatively, if you already have your repository cloned, you can simply point VS Code to the repository's directory and it should work out-of-the-box.

I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch [...]

This StackOverflow question seems to be the solution, if I understood your question correctly :)

It seems a bit too complicated for me (remember I don't use Git directly). I see two easy solutions: (1) I just delete my fork (keep a local copy of course), re-fork again, make the changes again (from my local copy), and commit to a new branch; or (2) I create a new branch from my master, and PR from that new branch.
If (2) is OK, I'll do that.

> > I had to commit in the meantime so I committed to (my) master branch... Is there a way to create the PR to another branch [...] > > [This StackOverflow question](https://stackoverflow.com/questions/1628563/move-the-most-recent-commits-to-a-new-branch-with-git) seems to be the solution, if I understood your question correctly :) It seems a bit too complicated for me (remember I don't use Git directly). I see two easy solutions: (1) I just delete my fork (keep a local copy of course), re-fork again, make the changes again (from my local copy), and commit to a new branch; or (2) I create a new branch from my master, and PR from that new branch. If (2) is OK, I'll do that.

It has integrated Git support which makes it possible to clone your repo and make commits, pushes and pulls directly from within the editor. Alternatively, if you already have your repository cloned, you can simply point VS Code to the repository's directory and it should work out-of-the-box.

Very easy to use and works perfectly indeed (it's a shame that it's owned by MS...).

> It has integrated Git support which makes it possible to clone your repo and make commits, pushes and pulls directly from within the editor. Alternatively, if you already have your repository cloned, you can simply point VS Code to the repository's directory and it should work out-of-the-box. Very easy to use and works perfectly indeed (it's a shame that it's owned by MS...).

Last question (for now): I have tried to make it look as if the user was JohnDoe, but of course I'm not. So I edited the images, but the easiest would be to have access to the same JohnDoe account that you used for the "Getting Started" guide. Would that be possible?

Last question (for now): I have tried to make it look as if the user was JohnDoe, but of course I'm not. So I edited the images, but the easiest would be to have access to the same JohnDoe account that you used for the "Getting Started" guide. Would that be possible?

If (2) is OK, I'll do that.

I'd not recommend making PRs from your fork's master branch, because it complicates things a lot if a PR is stalled/blocked or (unlikely) rejected.

It would be best to move related changesets to individual branches and have a PR for each of them (i.e. if you're writing an article on markdown and one on the API at the same time, put the commits on two separate branches, depending on which article they belong to).

You can use Git to do that, but I can understand if that's getting a bit complicated (Git is a mighty but slightly frightening beast 😉).

So, option number 1 might be the way to go.

> If (2) is OK, I'll do that. I'd not recommend making PRs from your fork's master branch, because it complicates things a lot if a PR is stalled/blocked or (unlikely) rejected. It would be best to move related changesets to individual branches and have a PR for each of them (i.e. if you're writing an article on markdown and one on the API at the same time, put the commits on two separate branches, depending on which article they belong to). You can use Git to do that, but I can understand if that's getting a bit complicated (Git is a mighty but slightly frightening beast :wink:). So, option number 1 might be the way to go.

With JohnDoe you mean Knut the icebear, right? :)

There was the idea earlier to give Documentation contributors access to that account. It didn't move forward, as it was a side-track in a now closed issue, but I think we should pick that up again. I'm not sure yet though how to best share the credentials to the Knut account in a safe way though.

Posting the password for grabs in this repository won't fly for pretty obvious reasons 😉 Maybe @n or @hw have an idea how to solve this?

For the time being, you could take the avatar from the Knut account and use it to create your own testing account on codeberg-test.org (the avatar is public domain / CC0-licensed).

With JohnDoe you mean Knut the icebear, right? :) There was the idea earlier to give Documentation contributors access to that account. It didn't move forward, as it was a side-track in a now closed issue, but I think we should pick that up again. I'm not sure yet though how to best share the credentials to the Knut account in a safe way though. Posting the password for grabs in this repository won't fly for pretty obvious reasons :wink: Maybe @n or @hw have an idea how to solve this? For the time being, you could take the avatar from the Knut account and use it to create your own testing account on codeberg-test.org (the avatar is public domain / CC0-licensed).

For convenience, that would be the one attached below

For convenience, that would be the one attached below
n commented 2 years ago
Collaborator

Posting the password for grabs in this repository won't fly for pretty obvious reasons 😉 Maybe @n or @hw have an idea how to solve this?

Would a private repo on the docs organization suffice? If necessary, we could also use GPG for encryption though I don't think it's necessary.

We'd also need official permission because the ToS disallows credential sharing.

> Posting the password for grabs in this repository won't fly for pretty obvious reasons :wink: Maybe @n or @hw have an idea how to solve this? Would a private repo on the [docs organization](https://codeberg.org/docs) suffice? If necessary, we could also use GPG for encryption though I don't think it's necessary. We'd also need official permission because the [ToS disallows credential sharing](https://codeberg.org/docs).

Yes, I think a private repo there would work well for frequent contributors and maintainers of Documentation.

For occasional or one-time contributors, it might be better to allow TODO Screenshot and have the screenshots created by one of the maintainers during review, also with #52 in mind.

Yes, I think a private repo there would work well for frequent contributors and maintainers of Documentation. For occasional or one-time contributors, it might be better to allow `TODO Screenshot` and have the screenshots created by one of the maintainers during review, also with #52 in mind.

With JohnDoe you mean Knut the icebear, right? :)

There was the idea earlier to give Documentation contributors access to that account. It didn't move forward, as it was a side-track in a now closed issue, but I think we should pick that up again. I'm not sure yet though how to best share the credentials to the Knut account in a safe way though.

Posting the password for grabs in this repository won't fly for pretty obvious reasons 😉 Maybe @n or @hw have an idea how to solve this?

For the time being, you could take the avatar from the Knut account and use it to create your own testing account on codeberg-test.org (the avatar is public domain / CC0-licensed).

This all sounds like a good idea. I meant a different repo/user though:
https://docs.codeberg.org/git/clone-commit-via-http/

> With JohnDoe you mean Knut the icebear, right? :) > > There was the idea earlier to give Documentation contributors access to that account. It didn't move forward, as it was a side-track in a now closed issue, but I think we should pick that up again. I'm not sure yet though how to best share the credentials to the Knut account in a safe way though. > > Posting the password for grabs in this repository won't fly for pretty obvious reasons :wink: Maybe @n or @hw have an idea how to solve this? > > For the time being, you could take the avatar from the Knut account and use it to create your own testing account on codeberg-test.org (the avatar is public domain / CC0-licensed). This all sounds like a good idea. I meant a different repo/user though: https://docs.codeberg.org/git/clone-commit-via-http/

I'd not recommend making PRs from your fork's master branch, because it complicates things a lot if a PR is stalled/blocked or (unlikely) rejected.

It would be best to move related changesets to individual branches and have a PR for each of them (i.e. if you're writing an article on markdown and one on the API at the same time, put the commits on two separate branches, depending on which article they belong to).

You can use Git to do that, but I can understand if that's getting a bit complicated (Git is a mighty but slightly frightening beast 😉).

So, option number 1 might be the way to go.

OK, I'll give my best to do that correctly!
Is there documentation on how to commit on a separate branch using VScode? Or is it just "create new branch from" and then "commit"? Or maybe I'll just use the web interface in this case...!

> I'd not recommend making PRs from your fork's master branch, because it complicates things a lot if a PR is stalled/blocked or (unlikely) rejected. > > It would be best to move related changesets to individual branches and have a PR for each of them (i.e. if you're writing an article on markdown and one on the API at the same time, put the commits on two separate branches, depending on which article they belong to). > > You can use Git to do that, but I can understand if that's getting a bit complicated (Git is a mighty but slightly frightening beast :wink:). > > So, option number 1 might be the way to go. OK, I'll give my best to do that correctly! Is there documentation on how to commit on a separate branch using VScode? Or is it just "create new branch from" and then "commit"? Or maybe I'll just use the web interface in this case...!
n commented 2 years ago
Collaborator

JohnDoe was used previously by @buhtz I think. That was before @lhinderberger came up with the idea for Knut.

JohnDoe was used previously by @buhtz I think. That was before @lhinderberger came up with the idea for Knut.

JohnDoe was used previously by @buhtz I think. That was before @lhinderberger came up with the idea for Knut.

OK, I will then re-do the screenshots with "knut" :) I had to call it "PolarBear" though, because "knut" is already registered.

> JohnDoe was used previously by @buhtz I think. That was before @lhinderberger came up with the idea for Knut. OK, I will then re-do the screenshots with "knut" :) I had to call it "PolarBear" though, because "knut" is already registered.
n commented 2 years ago
Collaborator

It looks like you can create a branch like this:

It looks like you can create a branch like this: ![](https://codeberg.org/attachments/5d65b79a-a577-400f-9581-5f9865a2cefb)

@n @lhinderberger I have created the first pull request (#76). Before I do it for the rest of what I've written, can you please let me know if I should do things differently (from branching, to writing style...)?

@n @lhinderberger I have created the first pull request (#76). Before I do it for the rest of what I've written, can you please let me know if I should do things differently (from branching, to writing style...)?

@ivan-paleo suggested documenting the Git-related parts of the web interface in greater detail.

I have created a PR #78 on just that. Waiting for feedback :)

> @ivan-paleo suggested documenting the Git-related parts of the web interface in greater detail. I have created a PR #78 on just that. Waiting for feedback :)
Collaborator

Do we need this issue anymore?

The PR has been merged and there are enough small to medium sized issue for specific topics.
I think we can close this.

Do we need this issue anymore? The PR has been merged and there are enough small to medium sized issue for specific topics. I think we can close this.
n closed this issue 1 year ago
Sign in to join this conversation.
No Milestone
No Assignees
4 Participants
Notifications
Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Codeberg/Documentation#67
Loading…
There is no content yet.