Promise this is the last thread i'll start til next week, but back on the docs train a little bit :)
So, how does the team think about mixing up how the team works and communicates? im thinking two seperate ideas here:
1. Archive this mailing list and move discussion for docs over to discussion.fedoraproject.org 2. Clean up all the docs repos, and move them to gitlab (specifically gitlab.com/fedora/docs) -- obviously this is a big and contentious one, but it would allow us to have subgroups for our tooling and docs, making it easier to group this stuff out. Also the way gitlab shows all tickets for groups will allow us to see issues across all our docs repos, rather than following many many repos.
cheers, ryanlerch
Ryan Lerch rlerch@redhat.com wrote: ...
- Clean up all the docs repos, and move them to gitlab (specifically gitlab.com/fedora/docs) -- obviously this is a big and contentious one, but it would allow us to have subgroups for our tooling and docs, making it easier to group this stuff out. Also the way gitlab shows all tickets for groups will allow us to see issues across all our docs repos, rather than following many many repos.
As a newcomer to Fedora docs, I have definitely struggled to find the repo I'm looking for, though I can't say whether that's a result of lack of organisation, repo naming/descriptions, or simply the number of repos.
Allan
On Thu, Dec 9, 2021 at 10:59 PM Ryan Lerch rlerch@redhat.com wrote:
- Archive this mailing list and move discussion for docs over to discussion.fedoraproject.org
I'd be okay with that. The more stuff that moves to Discussion, the less it throws me off when something isn't in my mail box. :-) But I'm also fine with keeping it as a mailing list if that works for the majority of contributors.
- Clean up all the docs repos, and move them to gitlab (specifically gitlab.com/fedora/docs) -- obviously this is a big and contentious one, but it would allow us to have subgroups for our tooling and docs, making it easier to group this stuff out. Also the way gitlab shows all tickets for groups will allow us to see issues across all our docs repos, rather than following many many repos.
Are you suggesting putting all of the docs in one repo? Because that idea makes me very sad from an ACL perspective. If you're talking about just putting the repos in a docs namespace, I can see the appeal, but IMO it's better to keep the docs close to the teams writing it. In fact, one of the things I've been meaning to push on the Council is combining the docs and tickets repos into one repo. Same for FESCo.
There's probably some docs repo consolidation we can do, but *all* seems like too much without a better understanding of the benefits.
On Fri, Dec 10, 2021 at 11:00 AM Allan Day aday@redhat.com wrote:
As a newcomer to Fedora docs, I have definitely struggled to find the repo I'm looking for, though I can't say whether that's a result of lack of organisation, repo naming/descriptions, or simply the number of repos.
I tend to go to the docs I'm interested in and then click the "Edit this page" button to get the repo I want. It's not an ideal workflow, but it works.
On Tue, Dec 14, 2021 at 7:17 AM Ben Cotton bcotton@redhat.com wrote:
On Thu, Dec 9, 2021 at 10:59 PM Ryan Lerch rlerch@redhat.com wrote:
- Archive this mailing list and move discussion for docs over to discussion.fedoraproject.org
I'd be okay with that. The more stuff that moves to Discussion, the less it throws me off when something isn't in my mail box. :-) But I'm also fine with keeping it as a mailing list if that works for the majority of contributors.
- Clean up all the docs repos, and move them to gitlab (specifically gitlab.com/fedora/docs) -- obviously this is a big and contentious one, but it would allow us to have subgroups for our tooling and docs, making it easier to group this stuff out. Also the way gitlab shows all tickets for groups will allow us to see issues across all our docs repos, rather than following many many repos.
Are you suggesting putting all of the docs in one repo? Because that idea makes me very sad from an ACL perspective.
No, more just about organizing and tidying the repos we have.
If you're talking about just putting the repos in a docs namespace, I can see the appeal, but IMO it's better to keep the docs close to the teams writing it. In fact, one of the things I've been meaning to push on the Council is combining the docs and tickets repos into one repo. Same for FESCo.
Definitely keeping the community docs where those subteams want them. But for the user documentation that the documentation team "owns" move this and organize it. (Maybe even document where the community docs come from too)
cheers, ryanlerch
There's probably some docs repo consolidation we can do, but *all* seems like too much without a better understanding of the benefits.
On Fri, Dec 10, 2021 at 11:00 AM Allan Day aday@redhat.com wrote:
As a newcomer to Fedora docs, I have definitely struggled to find the repo I'm looking for, though I can't say whether that's a result of lack of organisation, repo naming/descriptions, or simply the number of repos.
I tend to go to the docs I'm interested in and then click the "Edit this page" button to get the repo I want. It's not an ideal workflow, but it works.
-- Ben Cotton He / Him / His Fedora Program Manager Red Hat TZ=America/Indiana/Indianapolis _______________________________________________ docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
On Fri, Dec 10, 2021 at 03:57:30AM -0000, Ryan Lerch wrote:
- Archive this mailing list and move discussion for docs over to
discussion.fedoraproject.org
I'm _definitely_ in favor of this.
I do think we should wait until I'm done with the Discussion site reorg, which I'm going to do as a mini-project over the holiday break.
- Clean up all the docs repos, and move them to gitlab (specifically
gitlab.com/fedora/docs) -- obviously this is a big and contentious one,
And I'm cautiously in favor of this.
On Tue, Dec 14, 2021 at 9:13 AM Matthew Miller mattdm@fedoraproject.org wrote:
On Fri, Dec 10, 2021 at 03:57:30AM -0000, Ryan Lerch wrote:
- Archive this mailing list and move discussion for docs over to
discussion.fedoraproject.org
I'm _definitely_ in favor of this.
I do think we should wait until I'm done with the Discussion site reorg, which I'm going to do as a mini-project over the holiday break.
Fantastic -- do we need to get a +1 from a number of active contributors to move forward? (sorry been a while since i was here in docs land!)
cheers, ryanlerch
- Clean up all the docs repos, and move them to gitlab (specifically
gitlab.com/fedora/docs) -- obviously this is a big and contentious one,
And I'm cautiously in favor of this.
-- Matthew Miller mattdm@fedoraproject.org Fedora Project Leader _______________________________________________ docs mailing list -- docs@lists.fedoraproject.org To unsubscribe send an email to docs-leave@lists.fedoraproject.org Fedora Code of Conduct: https://docs.fedoraproject.org/en-US/project/code-of-conduct/ List Guidelines: https://fedoraproject.org/wiki/Mailing_list_guidelines List Archives: https://lists.fedoraproject.org/archives/list/docs@lists.fedoraproject.org Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
On Tue, Dec 14, 2021 at 09:29:41AM +1000, Ryan Lerch wrote:
Fantastic -- do we need to get a +1 from a number of active contributors to move forward? (sorry been a while since i was here in docs land!)
I think in general this group has been very stagnant. (Thank you very much to the several of you who have been moving things forward nonetheless, though!) I think therefore, now is a fine time to do it.
Well, after the reorg, as I mentioned. But let's plan for it, unless anyone has _really strong and convincing_ objections. (Note that while Discourse is definitely web-primary, it has a mechanism for email notifications, including "send every post as an email" mode, and you can respond to those. So if you prefer a "push" model, that's still there.)
On Mon, Dec 13, 2021 at 10:03:12PM -0500, Matthew Miller wrote:
Well, after the reorg, as I mentioned. But let's plan for it, unless anyone has _really strong and convincing_ objections. (Note that while Discourse is
I haven't heard any objections. Let's, therefore, make the new home here:
https://discussion.fedoraproject.org/tag/docs
On Sat, Jan 1, 2022 at 8:08 PM Matthew Miller mattdm@fedoraproject.org wrote:
I haven't heard any objections. Let's, therefore, make the new home here:
I'll take care of the back half of making this true (closing the mailing list, updating references in docs, etc).
On Wed, Jan 05, 2022 at 01:05:31PM -0500, Ben Cotton wrote:
I haven't heard any objections. Let's, therefore, make the new home here: https://discussion.fedoraproject.org/tag/docs
I'll take care of the back half of making this true (closing the mailing list, updating references in docs, etc).
Thank you, Ben!
Happy New Year Docs I have been a Fedora biggot for about 15 years. I am a retired senior with an interest in the grammar as used within the docs. I rewrote some for my own pastime, I am not into using esoteric words in descriptions, but in spelling, punctuation, and in paragraph construction. For what it is worth, I am bilingual Candian-English, Canadian French with some Spanish. As a pastime, I have edited the published docs for myself. Yes, my docs are more clear than the original, and more suited to the reader, whom I presume to be the beginner to Linux.
As per relocating to: https://discussion.fedoraproject.org/tag/docs, I can certainly add a new bookmark. After the dust settles, I would like to find a way to have my document tweaking reviewed and integrated into the mother doc.
Regards from Canada Leslie Leslie Satenstein Montréal Québec, Canada
On Wednesday, January 5, 2022, 01:05:54 p.m. EST, Ben Cotton bcotton@redhat.com wrote:
On Sat, Jan 1, 2022 at 8:08 PM Matthew Miller mattdm@fedoraproject.org wrote:
I haven't heard any objections. Let's, therefore, make the new home here:
#docs topics
I'll take care of the back half of making this true (closing the mailing list, updating references in docs, etc).
On Mon, Dec 13, 2021 at 6:31 PM Ryan Lerch rlerch@redhat.com wrote:
Fantastic -- do we need to get a +1 from a number of active contributors to move forward? (sorry been a while since i was here in docs land!)
Docs isn't really a structured team lately, so I'd say if no one has raised objections by the time Matthew has finished with the site reorg, then consider that permission. :-)
On Mon, Dec 13, 2021 at 6:22 PM Ryan Lerch rlerch@redhat.com wrote:
Definitely keeping the community docs where those subteams want them. But for the user documentation that the documentation team "owns" move this and organize it. (Maybe even document where the community docs come from too)
Okay, that makes sense. I don't see the benefits of moving the repos to GitLab at this point, so I'd welcome you selling me on that. One of my December projects is to put together a plan for revitalizing the Docs team so that it's more of a team and less of a "uncoordinated contributions from individuals (who are doing excellent work)". So a rethink of the repo layout could be part of that.
Ben Cotton bcotton@redhat.com wrote: ...
Okay, that makes sense. I don't see the benefits of moving the repos to GitLab at this point, so I'd welcome you selling me on that. ...
One of the main selling points of Gitlab, for me at least, is the online editing experience. There's a web IDE, which has syntax highlighting and validation. More importantly, it allows someone to submit changes without having to be familiar with PR workflows - you just click the "commit" button and it will create an MR for you. (A screenshot of what this commit step looks like in Gitlab: https://imgur.com/a/IBKufW8 .)
Creating a fork, cloning it, and then creating a PR through Pagure is a bit involved and requires existing knowledge, which will surely put some potential contributors off. Some of these Gitlab features could help us to overcome those issues.
Allan
On Tue, Dec 14, 2021 at 12:19 PM Allan Day aday@redhat.com wrote:
One of the main selling points of Gitlab, for me at least, is the online editing experience. There's a web IDE, which has syntax highlighting and validation. More importantly, it allows someone to submit changes without having to be familiar with PR workflows - you just click the "commit" button and it will create an MR for you.
Well that's super compelling. Do you have to have commit access to the repo for that to work, or will it make a fork in the background for folks? I like the online editing experience for regular contributors who want it, but I REALLY like it for people who want to make a "drive-by" contribution.
Ben Cotton bcotton@redhat.com wrote: ...
One of the main selling points of Gitlab, for me at least, is the online editing experience. There's a web IDE, which has syntax highlighting and validation. More importantly, it allows someone to submit changes without having to be familiar with PR workflows - you just click the "commit" button and it will create an MR for you.
Well that's super compelling. Do you have to have commit access to the repo for that to work, or will it make a fork in the background for folks?
If you don't have commit access and you click on the Web IDE button, a banner appears which says that you need to fork. The banner itself contains a fork button - if you press it, it creates the fork and then drops you into the web IDE from that single click. So, there's an extra step, but they've boiled it down to a single additional click.
You would need to be logged in for this to work, of course.
I like the online editing experience for regular contributors who want it, but I REALLY like it for people who want to make a "drive-by" contribution.
Also for getting new contributors interested - it's a great way to get started.
Allan
One of the main selling points of Gitlab, for me at least, is the online editing experience. There's a web IDE, which has syntax highlighting and validation. More importantly, it allows someone to submit changes without having to be familiar with PR workflows - you just click the "commit" button and it will create an MR for you. (A screenshot of what this commit step looks like in Gitlab: https://imgur.com/a/IBKufW8 .)
I think the Web IDE is a great selling point for GitLab, but not to *oversell*, while Gitlab has good support for previewing asciidoc when browsing repositories, you don't get either syntax highlighting or "live preview" for asciidoc in the IDE. These both seem like very feasible additions - not big additions. (Live preview is https://gitlab.com/gitlab-org/gitlab/-/issues/85134, syntax highlighting during editing would require writing a grammar for https://microsoft.github.io/monaco-editor/monarch.html)
And of course, GitlLb is unaware of Antora, so various things won't render correctly. Some of these (embedded images) could probably be fixed with small additions to the Gitlab asciidoc support. Other (inter-component links) seem harder.
That all being said, the GitLab Web IDE seems to be the most feasible path to having a workflow where a newcomer could come in and make significant contributions to the Fedora docs, without needing install tools, learn the git command line, do local builds, etc.
And that's important!
Regards, Owen
Owen Taylor otaylor@fedoraproject.org wrote:
One of the main selling points of Gitlab, for me at least, is the online editing experience. There's a web IDE, which has syntax highlighting and validation. More importantly, it allows someone to submit changes without having to be familiar with PR workflows
...
I think the Web IDE is a great selling point for GitLab, but not to *oversell*, while Gitlab has good support for previewing asciidoc when browsing repositories, you don't get either syntax highlighting or "live preview" for asciidoc in the IDE.
True, preview is important, and it seems that you only get that in the web IDE for Markdown (at least, I don't see it for reST or Asciidoc).
The automatic MR creation is awesome and I can even imagine people using it in combination with local tools for editing and preview, but if we could have Gitlab support a complete workflow that would be infinitely superior.
Allan
On Tue, Dec 14, 2021 17:18:40 +0000, Allan Day wrote:
Ben Cotton bcotton@redhat.com wrote: ...
Okay, that makes sense. I don't see the benefits of moving the repos to GitLab at this point, so I'd welcome you selling me on that. ...
One of the main selling points of Gitlab, for me at least, is the online editing experience. There's a web IDE, which has syntax highlighting and validation. More importantly, it allows someone to submit changes without having to be familiar with PR workflows - you just click the "commit" button and it will create an MR for you. (A screenshot of what this commit step looks like in Gitlab: https://imgur.com/a/IBKufW8 .)
Creating a fork, cloning it, and then creating a PR through Pagure is a bit involved and requires existing knowledge, which will surely put some potential contributors off. Some of these Gitlab features could help us to overcome those issues.
For completeness, I want to note that pagure does have this feature. You should see a "fork and edit" button when you click "Edit this page" in docs, and clicking that forks the repo for you and takes you to the web editor where you can make your changes and commit to create a PR.
The pagure editor is not a full IDE, though.
Example screenshot attached.
-
Allan Day -
Ankur Sinha -
Ben Cotton -
Leslie S Satenstein -
Matthew Miller -
Owen Taylor -
Ryan Lerch