Forgejo documentation #67

caesar commented 2022年12月15日 11:11:48 +01:00

We need to publish our own documentation site.

There are a few possible strategies I can think of:

1. Maintain the existing Gitea documentation as a soft fork en exactly the same way as Forgejo itself. We will have to take care of, at minimum:

   • Replacing Gitea with Forgejo and also changing any links
   • Altering and adding any documentation that's specific to Forgejo
   • Dealing with localization of the above changes

   We'll have to use feature branches and rebase them regularly on latest Gitea main like with Forgejo itself.

2. Make a hard fork of the existing Gitea documention, after which we can make any changes we like.
   We will have to regularly "merge" new documentation for new Gitea features (or re-write it ourselves). But I think this will be much less work than option 1.
   It will also free us to make a lot of major changes without worrying about maintainability. It would be easy to massively improve on Gitea's documentation.

3. Write documentation from scratch. Not really an option unless a good technical writer wants to volunteer a lot of their time in the very near future...

---

I think I would be in favour of option 2, which would also make it easier to build our own custom documentation site without having to worry about maintaining changes relative to Gitea's docs site.

Assuming we go with option 2, I volunteer to get started on this work after the launch, and create a docs site that will match https://forgejo.org.

---

Note: for what it's worth, the Gitea docs are Apache-licensed.

We need to publish our own documentation site. There are a few possible strategies I can think of: 1. Maintain the [existing Gitea documentation](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/docs) as a *soft fork* en exactly the same way as Forgejo itself. We will have to take care of, at minimum: - Replacing `Gitea` with `Forgejo` and also changing any links - Altering and adding any documentation that's specific to Forgejo - Dealing with localization of the above changes We'll have to use feature branches and rebase them regularly on latest Gitea `main` like with Forgejo itself. 2. Make a *hard fork* of the existing Gitea documention, after which we can make any changes we like. We will have to regularly "merge" new documentation for new Gitea features (or re-write it ourselves). But I think this will be much less work than option 1. It will also free us to make a lot of major changes without worrying about maintainability. It would be easy to massively improve on Gitea's documentation. 3. Write documentation from scratch. Not really an option unless a good technical writer wants to volunteer a lot of their time in the very near future... --- I think I would be in favour of **option 2**, which would also make it easier to build our own custom documentation site without having to worry about maintaining changes relative to Gitea's docs site. Assuming we go with option 2, I volunteer to get started on this work after the launch, and create a docs site that will match https://forgejo.org. --- Note: for what it's worth, the Gitea docs are Apache-licensed.

circlebuilder commented 2022年12月16日 07:30:44 +01:00

I don't know the extent to which this is already done, but the other day I was thinking about this subject and musing that:

• All docs are baked into the Forgejo release. So each install has local access to full docs.

• Codeberg docs would become adopted into Forgejo as the basis for docs.

Now of course each Gitea instance would likely want to customize and extend the documentation, Codeberg itself is a good example (they have extra services etc), so this docs integration should make that easy. But also it should make it easy to upstream docs improvemnents to Forgejo.

By making the docs integrated like this:

• They become part of each instance and, if not accurate, provide instance admins clear incentive to update them.
• And at the same time takes away the barrier to contribution to the upstream project.

I don't know the extent to which this is already done, but the other day I was thinking about this subject and musing that: - All docs are baked into the Forgejo release. So each install has local access to full docs. - Codeberg docs would become adopted into Forgejo as the basis for docs. Now of course each Gitea instance would likely want to customize and extend the documentation, Codeberg itself is a good example (they have extra services etc), so this docs integration should make that easy. But also it should make it easy to upstream docs improvemnents to Forgejo. By making the docs integrated like this: - They become part of each instance and, if not accurate, provide instance admins clear incentive to update them. - And at the same time takes away the barrier to contribution to the upstream project.

Ghost commented 2022年12月16日 14:11:15 +01:00

I'm in favor of option 2 and also volunteer to help. Codeberg has a lot of documentation, there is a lot of material available to get started. The last hackaton had interesting discussions on the matter.

I'm in favor of option 2 and also volunteer to help. Codeberg has a lot of documentation, there is a lot of material available to get started. The last hackaton had interesting discussions on the matter.

winnewoerp commented 2022年12月19日 21:29:51 +01:00

If we go with option 2 proposed by @caesar and @dachary, I will be glad to help getting things started by doing necessary editorial work, even if part of it is monotonous "assembly line work".

If we go with **option 2** proposed by @caesar and @dachary, I will be glad to help getting things started by doing necessary editorial work, even if part of it is monotonous "assembly line work".

caesar commented 2023年01月09日 13:25:22 +01:00

I'm unfortunately not going to have time to work on this in the near future (next couple of months), so I'm unassigning myself.

I'm still happy to work on it at a later date but hopefully someone else will be available to get something started sooner.

I'm unfortunately not going to have time to work on this in the near future (next couple of months), so I'm unassigning myself. I'm still happy to work on it at a later date but hopefully someone else will be available to get something started sooner.

Ghost commented 2023年01月09日 15:28:08 +01:00

I would be happy to contribute to the effort if someone takes the lead. But I'm still unsure if I should take the lead or not: I would need to sort out how to prioritize this. I'll unassigned myself with this promise: as soon as someone takes the lead on the documentation I'll work with them up to four hours per week.

In other words: if someone is willing to take the lead, they won't go it alone, I'll be there 😇

I would be happy to contribute to the effort if someone takes the lead. But I'm still unsure if I should take the lead or not: I would need to sort out how to prioritize this. I'll unassigned myself with this promise: as soon as someone takes the lead on the documentation I'll work with them up to four hours per week. In other words: if someone is willing to take the lead, they won't go it alone, I'll be there 😇

rdwz commented 2023年01月19日 14:21:31 +01:00

I can do a poc and use astro as well as we do already for the website

https://github.com/withastro/astro/tree/main/examples/docs
*just without algolia search

I can do a poc and use astro as well as we do already for the website https://github.com/withastro/astro/tree/main/examples/docs *just without algolia search

Ghost commented 2023年01月19日 19:43:08 +01:00

@redwerkz if you're willing to take the lead on this, I'll be happy to be an active participant.

@redwerkz if you're willing to take the lead on this, I'll be happy to be an active participant.

fsologureng commented 2023年01月19日 21:31:39 +01:00

I wish to read @fnetX comments with respect to the Hackaton work about documentation. I understand that there are work done in order to evaluating pro/cons and doing PoC.

I wish to read @fnetX comments with respect to the [Hackaton work about documentation](https://pad.ccc-p.org/kIRY5hpsRZemFQlMQm_60Q#upstreaming-the-docs). I understand that there are work done in order to evaluating pro/cons and doing PoC.

robbystk commented 2023年01月19日 21:45:15 +01:00

I'm trying to figure out the mechanics of Option 2. Option 2 is a hard fork of just the documentation. My understanding of Forgejo being a soft fork of Gitea is that Forgejo's changes will be rebased onto future changes to Gitea, and there is a workflow for maintaining this. It looks like the documentation is in the docs/ subdirectory of the Forgejo repository. How would a hard fork of the documentation coexist with the soft fork of Gitea? Would we extract the docs directory to a separate repo? or submodule? Or would we keep it in this repo and somehow exclude all upstream changes to that directory when rebasing?

If I understand how this should work, then maybe I or someone else can start this ball rolling.

I'm trying to figure out the mechanics of Option 2. Option 2 is a hard fork of just the documentation. My understanding of Forgejo being a soft fork of Gitea is that Forgejo's changes will be rebased onto future changes to Gitea, and there is a [workflow for maintaining this](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/CONTRIBUTING/WORKFLOW.md). It looks like the documentation is in [the docs/ subdirectory](https://codeberg.org/forgejo/forgejo/src/branch/forgejo/docs) of the Forgejo repository. How would a hard fork of the documentation coexist with the soft fork of Gitea? Would we extract the docs directory to a separate repo? or submodule? Or would we keep it in this repo and somehow exclude all upstream changes to that directory when rebasing? If I understand how this should work, then maybe I or someone else can start this ball rolling.

crystal commented 2023年01月19日 21:58:14 +01:00

My thoughts on the current documentation situation are covered in forgejo/forgejo#261 (comment)

Leaving a comment on this issue to detail what I would like to see

• Option 2 sounds good. I'm fully in favor of firing up a new repository and starting a hard fork of Gitea's docs, the docs directory in the source tree can be abandoned
• As mentioned in the linked comment, Codeberg has good end-user docs and Gitea has passable technical docs. Forgejo should strive to have a beautiful and easy to navigate documentation website that covers both in-depth, perhaps even with a distinct section for each.
• Gitea's documentation contains a number of grammatical errors and confusing, ambiguous, or just inadequate explanations of some features. This should be polished and some thought should be given to explaining things in a way that's easy to understand.

My thoughts on the current documentation situation are covered in https://codeberg.org/forgejo/forgejo/issues/261#issuecomment-776017 Leaving a comment on this issue to detail what I would like to see - Option 2 sounds good. I'm fully in favor of firing up a new repository and starting a hard fork of Gitea's docs, the docs directory in the source tree can be abandoned - As mentioned in the linked comment, Codeberg has good end-user docs and Gitea has passable technical docs. Forgejo should strive to have a beautiful and easy to navigate documentation website that covers both in-depth, perhaps even with a distinct section for each. - Gitea's documentation contains a number of grammatical errors and confusing, ambiguous, or just inadequate explanations of some features. This should be polished and some thought should be given to explaining things in a way that's easy to understand.

fnetX commented 2023年01月19日 22:42:20 +01:00

Gitea currently has no end-user documentation. This needs to be recreated. Either matching the version by baking into Forgejo, or by using some kind of docs.forgejo.org/<version> identifier.

Because motivation and potentially ways of maintaining this is different, I do not object to splitting admin docs from end-user docs and eventually focusing one one for now. But the admin docs also require a lot of work.

If a workflow is established, I think we should define it as a requirement that every new feature should be explained. This can be discussed in the PR review cycle (e.g. simple features / buttons could be excluded, but everything non-obvious or hidden features that users might not find (although the UI once you know about is intuitive) should be explained; and every config switch for admins should also have a description that goes beyond: "TOGGLE_X: Allows you to toggle X."

A very important thing I'd like for the admin docs is to share experiences (e.g. instead of just listing config switches, explain what you need to do to get the PROXY protocol up and running and which switches are related; or the whole subject of how to adjust queues and what to consider in production etc).

For reference, this is the Hackathon minutes: https://pad.ccc-p.org/kIRY5hpsRZemFQlMQm_60Q?both#upstreaming-the-docs I'm going through the arguments once more and see what my opinion is.

Gitea currently has no end-user documentation. This needs to be recreated. Either matching the version by baking into Forgejo, or by using some kind of `docs.forgejo.org/<version>` identifier. Because motivation and potentially ways of maintaining this is different, I do not object to splitting admin docs from end-user docs and eventually focusing one one for now. But the admin docs also require a lot of work. If a workflow is established, I think we should define it as a requirement that every new feature should be explained. This can be discussed in the PR review cycle (e.g. simple features / buttons could be excluded, but everything non-obvious or hidden features that users might not find (although the UI once you know about is intuitive) should be explained; and every config switch for admins should also have a description that goes beyond: "TOGGLE_X: Allows you to toggle X." A very important thing I'd like for the admin docs is to share experiences (e.g. instead of just listing config switches, explain what you need to do to get the PROXY protocol up and running and which switches are related; or the whole subject of how to adjust queues and what to consider in production etc). For reference, this is the Hackathon minutes: https://pad.ccc-p.org/kIRY5hpsRZemFQlMQm_60Q?both#upstreaming-the-docs I'm going through the arguments once more and see what my opinion is.

rdwz commented 2023年01月20日 18:14:04 +01:00

Would we extract the docs directory to a separate repo?

this!

just from the position of my proposal.

• it has it's own building
• it similar to our website so we achieve less technical fragmentation
• doesn't make sense to add complexity to any other existing repo
• having one more repo is not a trade off, at least at the early stage of now

> Would we extract the docs directory to a separate repo? this! just from the position of my proposal. - it has it's own building - it similar to our website so we achieve less technical fragmentation - doesn't make sense to add complexity to any other existing repo - having one more repo is not a trade off, at least at the early stage of now

rdwz commented 2023年01月20日 18:20:49 +01:00

Gitea currently has no end-user documentation.

We should also have a look how bighub does it: https://docs.github.com/en

A very important thing I'd like for the admin docs is to share experiences

YES. We are targeting for users being devs themselves, so shared knowledge needs a shared space and in the end more activity makes our community more inviting, we receive user feedback just as by their real needs..

• like how to migrate from gh? 😏
• or lots of how to forgejo yourself guides

> Gitea currently has no end-user documentation. We should also have a look how bighub does it: https://docs.github.com/en > A very important thing I'd like for the admin docs is to share experiences YES. We are targeting for users being devs themselves, so shared knowledge needs a shared space and in the end more activity makes our community more inviting, we receive user feedback just as by their real needs.. - like how to migrate from gh? 😏 - or lots of how to forgejo yourself guides

Ghost commented 2023年01月20日 18:31:37 +01:00

Codeberg has end user documentation https://docs.codeberg.org/

Codeberg has end user documentation https://docs.codeberg.org/

crystal commented 2023年01月21日 01:16:36 +01:00

@redwerkz Are you married to the idea of using Astro for this? Gitea's documentation uses Hugo and I think it would be easier to fork and adapt it if we used the same framework. Just an idea, Astro looks pretty, I had just never heard of it prior to looking at the source for the Forgejo website.

@redwerkz Are you married to the idea of using Astro for this? Gitea's documentation uses Hugo and I think it would be easier to fork and adapt it if we used the same framework. Just an idea, Astro looks pretty, I had just never heard of it prior to looking at the source for the Forgejo website.

rdwz commented 2023年01月23日 10:58:51 +01:00

@crystal it not just looks pretty its: astro > hugo

@crystal it not just looks pretty its: astro > hugo

crystal commented 2023年01月23日 11:10:45 +01:00

????

????

rdwz commented 2023年01月23日 11:26:12 +01:00

'>' bigger than

'>' bigger than

crystal commented 2023年01月23日 11:27:41 +01:00

I know what that means, I'm just very confused. I feel like you just pointed to two tools that are shaped completely differently and said "That one is objectively superior to the other one" without elaborating at all.

I know what that means, I'm just very confused. I feel like you just pointed to two tools that are shaped completely differently and said "That one is objectively superior to the other one" without elaborating at all.

Ghost commented 2023年01月23日 12:09:03 +01:00

@redwerkz given the recently heated discussion in the chat, it would be a lot better to clearly articulate what you mean. It may seem like a waste of time but it helps cool down. For instance instead of:

it not just looks pretty its: astro > hugo

You could write:

I think that astro is better than hugo because:

• it has this feature which hugo does not have
• etc.

I'm sure you can appreciate that not everyone is of the opinion that astro is better than hugo. The authors of hugo, for instance ;-)

Thanks for your understanding and your help to make the discussions relaxed and productive.

@redwerkz given the recently heated discussion in the chat, it would be a lot better to clearly articulate what you mean. It may seem like a waste of time but it helps cool down. For instance instead of: > it not just looks pretty its: astro > hugo You could write: > I think that astro is better than hugo because: > * it has this feature which hugo does not have > * etc. I'm sure you can appreciate that not everyone is of the opinion that astro is better than hugo. The authors of hugo, for instance ;-) Thanks for your understanding and your help to make the discussions relaxed and productive.

miku86 commented 2023年01月23日 18:08:00 +01:00

Please let's also consider things like:

• bus factor (amount of people contributing here who are familiar with techA vs. techB)
• amount of discoverable knowledge
• low friction for people who want to contribute
  ...

Please let's also consider things like: - bus factor (amount of people contributing here who are familiar with techA vs. techB) - amount of discoverable knowledge - low friction for people who want to contribute ...

Ghost commented 2023年01月23日 18:24:00 +01:00

For the record, @redwerkz and myself are going to move forward at https://codeberg.org/forgejo-contrib/documentation . There is no telling where that will go but ... it will go somewhere. It is the value of the https://codeberg.org/forgejo-contrib organization to allow for random experimentation. If something good comes out of our collective work, we will seek consensus and discuss how or when it can become part of the Forgejo project in a sustainable way.

For the record, @redwerkz and myself are going to move forward at https://codeberg.org/forgejo-contrib/documentation . There is no telling where that will go but ... it will go somewhere. It is the value of the https://codeberg.org/forgejo-contrib organization to allow for random experimentation. If something good comes out of our collective work, we will seek consensus and discuss how or when it can become part of the Forgejo project in a sustainable way.

gapodo commented 2023年01月23日 18:44:40 +01:00

Still mostly on a break, so I'm not aware of what happened in chat...

A couple of thoughts on the things mentioned here...

• Option 2 seems the most feasible one to me (as many others)
• I'd strongly oppose splitting docs from code, as docs closely relate to the version of Forgejo (Features, Issues, Limitations, Defaults, UI-Changes,...) and keeping them in sync, as well as keeping "stuff" documented becomes harder when it's not "one PR" but a separate task on a separate repo,...
• Splitting admin and user docs may be a good idea (different target group, different assumptions,...)
• Software to document with...
  • For technical docs (and therefore also the admin docs), I'd tend to go with something "usual" to tech docs like mdBook, no fancy CSS (though it could be added), easy to read without building (simple markdown) and a good search should be criteria for admin docs (no fuzz, no bling, cold hard facts)
    • Providing examples may sound tempting, though we should be careful on how much we put into the docs as maintaining changes in "tools that integrate / interface with forgejo" could become a huge task (how many reverse proxies are there, how many different versions and options,...)
  • For the user docs, theming / branding may be more important, so hugo (and yes also astro, though I've never seen it used for docs and would prefer a go framework) may be a good option.
  • In general, keeping dependencies and build effort for the docs low should be a goal to strive for
• Customizing docs on an instance to me is a "nice to have" that has to be thought through very well, as it's a huge rabbit hole to fall into
  • IIRC with the Codeberg hackathon there was discussion on hiding parts of the docs, which from my perspective isn't something we should do / enable, as it takes away from Forgejo as a product (we could add Banners showing that the feature isn't available on this instance, which would make it clear, that it doesn't work here, but is possible on Forgejo)
• It would be good if docs were mostly static assets (not rendered on each call), to optimize response times, preserve system resources,...

Over all, I'd tend to put in a vote for well established and used tools like mdBook and hugo as they reduce bus factor, are more accessible / more likely to be known by "drive by" contributors as well as the community as a whole.

Still mostly on a break, so I'm not aware of what happened in chat... A couple of thoughts on the things mentioned here... * Option 2 seems the most feasible one to me (as many others) * I'd strongly oppose splitting docs from code, as docs closely relate to the version of Forgejo (Features, Issues, Limitations, Defaults, UI-Changes,...) and keeping them in sync, as well as keeping "stuff" documented becomes harder when it's not "one PR" but a separate task on a separate repo,... * Splitting admin and user docs may be a good idea (different target group, different assumptions,...) * Software to document with... * For technical docs (and therefore also the admin docs), I'd tend to go with something "usual" to tech docs like mdBook, no fancy CSS (though it could be added), easy to read without building (simple markdown) and a good search should be criteria for admin docs (no fuzz, no bling, cold hard facts) * Providing examples may sound tempting, though we should be careful on how much we put into the docs as maintaining changes in "tools that integrate / interface with forgejo" could become a huge task (how many reverse proxies are there, how many different versions and options,...) * For the user docs, theming / branding may be more important, so hugo (and yes also astro, though I've never seen it used for docs and would prefer a go framework) may be a good option. * In general, keeping dependencies and build effort for the docs low should be a goal to strive for * Customizing docs on an instance to me is a "nice to have" that has to be thought through very well, as it's a huge rabbit hole to fall into * IIRC with the Codeberg hackathon there was discussion on hiding parts of the docs, which from my perspective isn't something we should do / enable, as it takes away from Forgejo as a product (we could add Banners showing that the feature isn't available on this instance, which would make it clear, that it doesn't work here, but is possible on Forgejo) * It would be good if docs were mostly static assets (not rendered on each call), to optimize response times, preserve system resources,... Over all, I'd tend to put in a vote for well established and used tools like mdBook and hugo as they reduce bus factor, are more accessible / more likely to be known by "drive by" contributors as well as the community as a whole.

fsologureng commented 2023年01月24日 22:25:38 +01:00

State of JS 2022 is now live and Astro had a HUGE year!!

This not appears to be relevant here. Can you explain the need?

> > State of JS 2022 is now live and Astro had a HUGE year!! This not appears to be relevant here. Can you explain the need?

gapodo commented 2023年01月24日 22:31:02 +01:00

Yes, absolutely unneeded, esp. when the proper conclusion from the state of JS (from a quick look) would be that there are docs only frameworks, that are more relevant... Though package usage / relevance surveys are almost always meaningless, as collecting real data isn't easy (how do you measure usage, how relevance, how do you group/cluster,...), also it's only a (questionable) survey for JS tools not technology in general.

If it's just pushing astro, I'd ask you to refrain from doing so, we've by now understood that you like it.

Yes, absolutely unneeded, esp. when the proper conclusion from the state of JS (from a quick look) would be that there are docs only frameworks, that are more relevant... Though package usage / relevance surveys are almost always meaningless, as collecting real data isn't easy (how do you measure usage, how relevance, how do you group/cluster,...), also it's only a (questionable) survey for JS tools not technology in general. If it's just pushing astro, I'd ask you to refrain from doing so, we've by now understood that you like it.

rdwz commented 2023年01月25日 00:01:18 +01:00

Yes, absolutely unneeded, esp. when the proper conclusion from the state of JS (from a quick look) would be that there are docs only frameworks, that are more relevant... Though package usage / relevance surveys are almost always meaningless, as collecting real data isn't easy (how do you measure usage, how relevance, how do you group/cluster,...), also it's only a (questionable) survey for JS tools not technology in general.

I understand, sorry that weren't the right links. implicitly i was telling you the 2.0 release comes with lots of infos to check out:
maybe try https://astro.build/blog/astro-2/
or https://docs.astro.build/en/concepts/why-astro/

> Yes, absolutely unneeded, esp. when the proper conclusion from the state of JS (from a quick look) would be that there are docs only frameworks, that are more relevant... Though package usage / relevance surveys are almost always meaningless, as collecting real data isn't easy (how do you measure usage, how relevance, how do you group/cluster,...), also it's only a (questionable) survey for JS tools not technology in general. I understand, sorry that weren't the right links. implicitly i was telling you the 2.0 release comes with lots of infos to check out: maybe try https://astro.build/blog/astro-2/ or https://docs.astro.build/en/concepts/why-astro/

Ghost commented 2023年01月25日 11:38:28 +01:00

For the record I'm working with @redwerkz on incubating a documentation at https://codeberg.org/forgejo-contrib/docs. In the best case scenario it will be something perfect that everybody will love. In the worst case scenario it will be a valuable contribution and a source of inspiration. I'm happy this is moving forward 🙂

For the record I'm working with @redwerkz on incubating a documentation at https://codeberg.org/forgejo-contrib/docs. In the best case scenario it will be something perfect that everybody will love. In the worst case scenario it will be a valuable contribution and a source of inspiration. I'm happy this is moving forward 🙂

Ghost commented 2023年02月16日 09:58:57 +01:00

As Forgejo 1.19 is approaching, there is a need for documentation: the blog & FAQ won't be enough. The primary reason is that Forgejo actions will be a focus and introduces significant changes & features as well as a runner that needs to be setup independently of Forgejo. Both Forgejo and the runner need to be released & documented properly.

As Forgejo 1.19 is approaching, there is a need for documentation: the blog & FAQ won't be enough. The primary reason is that Forgejo actions will be a focus and introduces significant changes & features as well as a runner that needs to be setup independently of Forgejo. Both Forgejo and the runner need to be released & documented properly.

Ghost commented 2023年02月16日 10:21:39 +01:00

Started a discussion to build upon the Codeberg user documentation rather than starting from scratch Codeberg/Documentation#277 (comment)

Side note: as someone authoring documentation I like that the Codeberg documentation repository https://codeberg.org/Codeberg/Documentation does not include any code, just CSS. I'm not eager to learn a framework, however excellent it is, and much prefer to work on a simple hierarchy of markdown files that will be displayed in a way that I do not have control over. The alternative being a more flexible framework that requires knowing more than markdown.

Started a discussion to build upon the Codeberg user documentation rather than starting from scratch https://codeberg.org/Codeberg/Documentation/issues/277#issuecomment-804691 Side note: as someone authoring documentation I like that the Codeberg documentation repository https://codeberg.org/Codeberg/Documentation does not include any code, just CSS. I'm not eager to learn a framework, however excellent it is, and much prefer to work on a simple hierarchy of markdown files that will be displayed in a way that I do not have control over. The alternative being a more flexible framework that requires knowing more than markdown.

earl-warren commented 2023年02月21日 15:58:15 +01:00

Regarding the internal CI, it would be good to have a list of features that are implemented. Since the intent is that it is compatible with GitHub actions, there is no need to document them: the GitHub documentation is the reference. There is however a need for the user to conveniently figure out what is not implemented instead of bumping into walls and guessing.

Regarding the internal CI, it would be good to have a list of features that are implemented. Since the intent is that it is compatible with GitHub actions, there is no need to document them: the GitHub documentation is the reference. There is however a need for the user to conveniently figure out what is **not** implemented instead of bumping into walls and guessing.

rdwz commented 2023年02月23日 12:18:56 +01:00

I'm not eager to learn a framework, however excellent it is, and much prefer to work on a simple hierarchy of markdown files that will be displayed in a way that I do not have control over.

No framework needed: ✅ Full Markdown support

> I'm not eager to learn a framework, however excellent it is, and much prefer to work on a simple hierarchy of markdown files that will be displayed in a way that I do not have control over. No framework needed: ✅ [Full Markdown support](https://codeberg.org/forgejo-contrib/docs#features)

Ryuno-Ki commented 2023年02月23日 12:22:07 +01:00

For the record: I set up a watch on the docs repository as I am interested in the subject. When I have slack time and no open issues I can pick up on the website I will look into whether I can contribute there.

At least until I know more about my grant application with NLnet.

For the record: I set up a watch on the docs repository as I am interested in the subject. When I have slack time and no open issues I can pick up on the website I will look into whether I can contribute there. At least until I know more about my grant application with NLnet.

Ghost commented 2023年02月23日 13:04:28 +01:00

I'm not eager to learn a framework, however excellent it is, and much prefer to work on a simple hierarchy of markdown files that will be displayed in a way that I do not have control over.

No framework needed: ✅ Full Markdown support

https://codeberg.org/forgejo-contrib/docs/src/branch/main/src/consts.ts this (and all other non markdown files) are what I'm worried about. And understanding this commit too forgejo-contrib/docs@7d897ff8bf

> > I'm not eager to learn a framework, however excellent it is, and much prefer to work on a simple hierarchy of markdown files that will be displayed in a way that I do not have control over. > > No framework needed: ✅ [Full Markdown support](https://codeberg.org/forgejo-contrib/docs#features) https://codeberg.org/forgejo-contrib/docs/src/branch/main/src/consts.ts this (and all other non markdown files) are what I'm worried about. And understanding this commit too https://codeberg.org/forgejo-contrib/docs/commit/7d897ff8bfa840a50e34bfdbf68e92238176c23b

Ghost commented 2023年02月27日 00:53:02 +01:00

The admin documentation is added at forgejo/website#114

The admin documentation is added at https://codeberg.org/forgejo/website/pulls/114

earl-warren commented 2023年02月27日 13:01:23 +01:00

Published at https://forgejo.codeberg.page/docs/v1.19/ and there is a followup PRs to link from the footer forgejo/website#115

Published at https://forgejo.codeberg.page/docs/v1.19/ and there is a followup PRs to link from the footer https://codeberg.org/forgejo/website/pulls/115

fsologureng commented 2023年02月27日 13:17:24 +01:00

@dachary

I'm not eager to learn a framework, however excellent it is, and much prefer to work on a simple hierarchy of markdown files that will be displayed in a way that I do not have control over.

No framework needed: ✅ Full Markdown support

https://codeberg.org/forgejo-contrib/docs/src/branch/main/src/consts.ts this (and all other non markdown files) are what I'm worried about. And understanding this commit too forgejo-contrib/docs@7d897ff8bf

This concerns hasn't being addressed

@dachary >> > I'm not eager to learn a framework, however excellent it is, and much prefer to work on a simple hierarchy of markdown files that will be displayed in a way that I do not have control over. >> >> No framework needed: ✅ [Full Markdown support](https://codeberg.org/forgejo-contrib/docs#features) > >https://codeberg.org/forgejo-contrib/docs/src/branch/main/src/consts.ts this (and all other non markdown files) are what I'm worried about. And understanding this commit too https://codeberg.org/forgejo-contrib/docs/commit/7d897ff8bfa840a50e34bfdbf68e92238176c23b This concerns hasn't being addressed

Ghost commented 2023年02月27日 13:41:30 +01:00

Just to clarify I do not have concerns left on this matter.

Just to clarify I do not have concerns left on this matter.

Ryuno-Ki commented 2023年02月27日 14:21:49 +01:00

@fsologureng Perhaps we should break it into another issue then.

@dachary Thank you for taking the time to wrap up loose threads. We welcome you with open arms if you ever change your mind and want to re-join the community.

@fsologureng Perhaps we should break it into another issue then. @dachary Thank you for taking the time to wrap up loose threads. We welcome you with open arms if you ever change your mind and want to re-join the community.

fsologureng commented 2023年02月27日 14:38:38 +01:00

Well, I have a main concern here: the decision made without discussion to leave user-docs out of the documentation named now administrator guide.

@Ryuno-Ki AFAIU @dachary never left Forgejo, I haven't see credential changes or resigns to the security team up to here.

Well, I have a main concern here: the decision made without discussion to leave user-docs out of the documentation named now `administrator guide`. @Ryuno-Ki AFAIU \@dachary never left Forgejo, I haven't see credential changes or resigns to the security team up to here.

Ryuno-Ki commented 2023年02月27日 14:42:20 +01:00

See #173

Stepping down and leaving almost all communication channels is an indicator for this in my perspective. You are right that there appears no explicit written explanation.

I agree with you that administrator guide is not the only documentation we should put up. But we have it there and could move it to a sub-path in the future. That would free the /docs path segment to list different documentation types.

I'd like to see one for end-users as well as a technical one that explains the software architecture.

See https://codeberg.org/forgejo/meta/pulls/173 Stepping down and leaving almost all communication channels is an indicator for this in my perspective. You are right that there appears no explicit written explanation. I agree with you that administrator guide is not the only documentation we should put up. But we have it there and could move it to a sub-path in the future. That would free the `/docs` path segment to list different documentation types. I'd like to see one for end-users as well as a technical one that explains the software architecture.

Ghost commented 2023年02月27日 15:25:55 +01:00

Could you please move the discussions regarding my participation in Forgejo elsewhere? This is off-topic.

Another issue can be opened for the creation of a user documentation. This issue was about Forgejo having a documentation instead of not, now this is done and IMHO it can be closed.

Could you please move the discussions regarding my participation in Forgejo elsewhere? This is off-topic. Another issue can be opened for the creation of a user documentation. This issue was about Forgejo having a documentation instead of not, now this is done and IMHO it can be closed.

Ryuno-Ki commented 2023年02月27日 17:36:54 +01:00

Could you please move the discussions regarding my participation in Forgejo elsewhere? This is off-topic.

I reached out to you on the Fediverse a few days ago and are awaiting response.

> Could you please move the discussions regarding my participation in Forgejo elsewhere? This is off-topic. I reached out to you on the Fediverse a few days ago and are awaiting response.

rdwz commented 2023年03月06日 10:01:58 +01:00

https://codeberg.org/forgejo-contrib/docs/src/branch/main/src/consts.ts this (and all other non markdown files) are what I'm worried about.

Are these real worries, or is this more about ideology? Please have a look at the Readme

> https://codeberg.org/forgejo-contrib/docs/src/branch/main/src/consts.ts this (and all other non markdown files) are what I'm worried about. Are these real worries, or is this more about ideology? Please have a look at the [Readme](https://codeberg.org/forgejo-contrib/docs#sidebar-navigation)