Migrating the Fedora Developer Portal to Fedora Docs

[Ankur Sinha]

Hi folks,

(CC: docs ML)

I've seen the Fedora Developer portal continue to exist as a standalone
project separately from the Fedora docs, and I don't quite understand
why this is so. I think it'll be much better if the information there
was moved to the new Fedora docs---so that users and the community have
all the info they need in one place. It'll also imply that the
work/resources that are being used to develop and maintain whatever
platform the Developer Portal is using can be directed towards improving
the docs project.

What do you think?

I've started a discussion here. Please chime in:
https://github.com/developer-portal/website/issues/112

[Jean-Baptiste Holcroft]

Le 2021-01-13 11:15, Ankur Sinha a écrit :
> What do you think?

From an internationalization point of view, it would helps a lot.
Both Fedora docs and Websites can be translated, only developer portal 
is stuck in English only.

[Matthew Miller]

On Wed, Jan 13, 2021 at 10:15:47AM +0000, Ankur Sinha wrote:
> What do you think?

I think it's a good idea. Having one place to look makes things easier for
users, especially once we finally get search.

[Kevin Fenzi]

On Wed, Jan 13, 2021 at 10:15:47AM +0000, Ankur Sinha wrote:
> Hi folks,
>
> (CC: docs ML)
>
> I've seen the Fedora Developer portal continue to exist as a standalone
> project separately from the Fedora docs, and I don't quite understand
> why this is so. I think it'll be much better if the information there
> was moved to the new Fedora docs---so that users and the community have
> all the info they need in one place. It'll also imply that the
> work/resources that are being used to develop and maintain whatever
> platform the Developer Portal is using can be directed towards improving
> the docs project.
>
> What do you think?
>
> I've started a discussion here. Please chime in:
> https://github.com/developer-portal/website/issues/112

I'm in favor if you can convince them to do it. ;)

kevin

[Ankur Sinha]

On Wed, Jan 13, 2021 13:45:23 -0800, Kevin Fenzi wrote:
> <snip>
>
> I'm in favor if you can convince them to do it. ;)

Let's see how it goes :D

Incidentally: who am I convincing?

The wiki page doesn't list any names[1]. Is there a SIG or a team that
maintains this? Would this fall under Websites (or Mindshare or CommOps
or Infra?) since it doesn't seem to fall under Docs.

[1] https://fedoraproject.org/wiki/Websites/Developer#About_The_Project

[Kevin Fenzi]

On Thu, Jan 14, 2021 at 08:41:04AM +0000, Ankur Sinha wrote:
> On Wed, Jan 13, 2021 13:45:23 -0800, Kevin Fenzi wrote:
> > <snip>
> >
> > I'm in favor if you can convince them to do it. ;)
>
> Let's see how it goes :D
>
> Incidentally: who am I convincing?
>
> The wiki page doesn't list any names[1]. Is there a SIG or a team that
> maintains this? Would this fall under Websites (or Mindshare or CommOps
> or Infra?) since it doesn't seem to fall under Docs.
>
> [1] https://fedoraproject.org/wiki/Websites/Developer#About_The_Project

The following folks had permssions on the developer vm back when we had
that, otherwise I am not sure:

asamalik jstribny phracek pvalena

kevin

[Pavel Valena]

----- Original Message -----
> From: "Kevin Fenzi" 
> To: [e-mail], [e-mail]
> Sent: Thursday, January 14, 2021 6:44:56 PM
> Subject: Re: Migrating the Fedora Developer Portal to Fedora Docs
>
> On Thu, Jan 14, 2021 at 08:41:04AM +0000, Ankur Sinha wrote:
> > On Wed, Jan 13, 2021 13:45:23 -0800, Kevin Fenzi wrote:
> > > <snip>
> > >
> > > I'm in favor if you can convince them to do it. ;)
> >
> > Let's see how it goes :D
> >
> > Incidentally: who am I convincing?

Hello,

I'm afraid I'm the only one left who's currently active.
> > The wiki page doesn't list any names[1]. Is there a SIG or a team that
> > maintains this? Would this fall under Websites (or Mindshare or CommOps
> > or Infra?) since it doesn't seem to fall under Docs.
> >
> > [1] https://fedoraproject.org/wiki/Websites/Developer#About_The_Project
>
> The following folks had permssions on the developer vm back when we had
> that, otherwise I am not sure:

Yes, the built went fine in the VM, but and then it all crashed...
> asamalik jstribny phracek pvalena
>
> kevin

Let me repost what I said in the issue:

If it's up to me (as there're no notes from the other/previous maintainers), feel free to migrate the content.

I'd be hower sad to see the current functionality to go away, mainly:

-  mentions of individual page's authors
  -  edit button on the page, leading to directly editing the page
  -  web editor
  -  no git knowledge needed to submit changes

Unfortunately, I don't have any spare cycles to do anything like that (I don't have much for the maintenance either).

Regards,

[Ankur Sinha]

On Fri, Jan 15, 2021 07:37:23 -0500, Pavel Valena wrote:
> Hello,

Hi Pavel,

Thanks for chiming in.
> I'm afraid I'm the only one left who's currently active.
>
> <snip>
>
> Let me repost what I said in the issue:
>
> If it's up to me (as there're no notes from the other/previous
> maintainers), feel free to migrate the content.
>
> I'd be hower sad to see the current functionality to go away, mainly:
> mentions of individual page's authors

How important is this and what function does this serve? Is the idea
that the listed authors serve as points of contacts---they're in-charge
of the information on the page?

I don't think this is currently a requirement of the docs, but depending
on how important this is, we could look into whether the Antora system
allows this. Of course, one can go to the git history of the page etc.
to see who edited the page and so on.
> edit button on the page, leading to directly editing the page

The docs have this. If you click the "Edit this page" link in the top
right corner, it takes you straight to the source of the page in the
respective Pagure repository.
> web editor

^
Pagure has a web-editor too. When you click "Edit this page", you'll see
multiple options "Fork and edit" (or "Edit in your fork" if you already
have the fork) will take you to the web-editor on Pagure.
> no git knowledge needed to submit changes

Could you clarify on this? One has to fork and open a PR to contribute
to the devportal too, right?
> Unfortunately, I don't have any spare cycles to do anything like that
> (I don't have much for the maintenance either).

I think that's another reason to merge it with docs, which will be
managed by the community, both infrastructure and content wise.

[Pavel Valena]

----- Original Message -----
> From: "Ankur Sinha" 
> To: "Development discussions related to Fedora" 
> Cc: "For participants of the Documentation Project" 
> Sent: Friday, January 15, 2021 2:03:46 PM
> Subject: Re: Migrating the Fedora Developer Portal to Fedora Docs
>
> On Fri, Jan 15, 2021 07:37:23 -0500, Pavel Valena wrote:
> > Hello,
>
> Hi Pavel,
>
> Thanks for chiming in.
> > I'm afraid I'm the only one left who's currently active.
> >
> > <snip>
> >
> > Let me repost what I said in the issue:
> >
> > If it's up to me (as there're no notes from the other/previous
> > maintainers), feel free to migrate the content.
> >
> > I'd be hower sad to see the current functionality to go away, mainly:
> > mentions of individual page's authors
>
> How important is this and what function does this serve? Is the idea
> that the listed authors serve as points of contacts---they're in-charge
> of the information on the page?

Well, the main idea is that author's name is enouraging more people to help with updates / editing. Having a POC is nice as well, but I'm not sure whether this option was ever used. Nor am I sure lot of people noticed, so this is not a hard requirement.
> I don't think this is currently a requirement of the docs, but depending
> on how important this is, we could look into whether the Antora system
> allows this. Of course, one can go to the git history of the page etc.
> to see who edited the page and so on.

You're right, git provides this, that's where we generate it from.
> > edit button on the page, leading to directly editing the page
>
> The docs have this. If you click the "Edit this page" link in the top
> right corner, it takes you straight to the source of the page in the
> respective Pagure repository.
> > web editor
>
> ^
> Pagure has a web-editor too. When you click "Edit this page", you'll see
> multiple options "Fork and edit" (or "Edit in your fork" if you already
> have the fork) will take you to the web-editor on Pagure.

Well, that's all great then.
> > no git knowledge needed to submit changes
>
> Could you clarify on this? One has to fork and open a PR to contribute
> to the devportal too, right?

Yes, you're right, but I think the process for github is intuitive, and the contributor does not work with commandline (was my main point).

Pagure needs require FAS though, right? What are the ACLs? Can anyone open a PR? The process seems a bit more complicated, and I'm not sure how many people already have github account, compared to FAS (does any of them support oauth from 3rd party? I'm unsure).
> > Unfortunately, I don't have any spare cycles to do anything like that
> > (I don't have much for the maintenance either).
>
> I think that's another reason to merge it with docs, which will be
> managed by the community, both infrastructure and content wise.

Agreed. Well, if it migrates well :), anyway.

IMO the UX seems a lot friendlier with Developer Portal, with several overviews, and it's also more granular (more sub-pages). Is there such feature (or a limit) in quick-docs? Also, there's no search (which limits the usability for me at least).

I don't want to end up with few monolithic pages noone reads. (And it's aimed at developers, so english is almost natural I expect.)

We could duplicate the content, however (for a while) and see how it compares, if you insist. Some automated translation (mirroring) would be a win-win IMO. Though I'm unsure it can be done.

Regards,
Pavel
> --
> Thanks,
> Regards,
> Ankur Sinha "FranciscoD" (He / Him / His) |
> https://fedoraproject.org/wiki/User:Ankursinha
> Time zone: Europe/London

[Ankur Sinha]

On Fri, Jan 15, 2021 10:34:32 -0500, Pavel Valena wrote:
<snip>
> > Could you clarify on this? One has to fork and open a PR to contribute
> > to the devportal too, right?
>
> Yes, you're right, but I think the process for github is intuitive,
> and the contributor does not work with commandline (was my main
> point).
>
> Pagure needs require FAS though, right? What are the ACLs? Can anyone
> open a PR? The process seems a bit more complicated, and I'm not sure
> how many people already have github account, compared to FAS (does any
> of them support oauth from 3rd party? I'm unsure).

As far as I know, only FAS is enabled for pagure.io. I *think* that's
intentional, though---it allows integration with the rest of Fedora over
fedora-messaging and so on. A mirror of the repo on Pagure for PRs over
GitHub can always be maintained. Lots of projects already do it. Fpaste
is an example:

https://pagure.io/fpaste
https://github.com/sanjayankur31/fpaste

Anyone with an account on Pagure can open PRs. One can define groups for
access etc., pretty much the same as on GitHub.
> > > Unfortunately, I don't have any spare cycles to do anything like that
> > > (I don't have much for the maintenance either).
> >
> > I think that's another reason to merge it with docs, which will be
> > managed by the community, both infrastructure and content wise.
>
> Agreed. Well, if it migrates well :), anyway.
>
> IMO the UX seems a lot friendlier with Developer Portal, with several
> overviews, and it's also more granular (more sub-pages). Is there such
> feature (or a limit) in quick-docs? Also, there's no search (which
> limits the usability for me at least).

I'm afraid I don't know all the features of the Antora based system, so
someone from the Docs core team will have to chime in here.

The search function is high on the TODO list. I think @mattdm has spoken
to CPE about this too, so it's not too far on the horizon.

https://pagure.io/fedora-docs/docs-fp-o/issue/2
https://pagure.io/fedora-infrastructure/issue/6750
> I don't want to end up with few monolithic pages noone reads. (And
> it's aimed at developers, so english is almost natural I expect.)

Is there any information on how many people are reading the dev portal
now? We know lots of people are using the Docs now, and we are
frequently helping new folks write more quick-docs (over at Ask Fedora,
for example). We're using it as a gateway to contribution---lots of
users who tinker with their systems are happy to share their knowledge,
so we help them write new quick-docs on their topic of choice.
> We could duplicate the content, however (for a while) and see how it
> compares, if you insist. Some automated translation (mirroring) would
> be a win-win IMO. Though I'm unsure it can be done.

I am not insisting at all. I am only wondering if it makes sense to have
another platform with information that the Docs are already designed to
hold. It splits the resources, and it makes users wonder where they
should look for information.

I don't think temporarily duplicating information is a good way to go.
That just makes it two copies that need to be updated then. If an
agreement cannot be reached to migrate the info into Docs, I think it's
best to leave things as they are. The Docs team keeps working on the
Docs, and the Devportal team can keep working away there.

As a community member, I thought I'd ask. That's all :)

[Pavel Valena]

----- Original Message -----
> From: "Ankur Sinha" 
> To: [e-mail], "For participants of the Documentation Project" 
> Sent: Monday, January 18, 2021 12:31:10 PM
> Subject: Re: Migrating the Fedora Developer Portal to Fedora Docs
>
> On Fri, Jan 15, 2021 10:34:32 -0500, Pavel Valena wrote:
>
> <snip>
> > > Could you clarify on this? One has to fork and open a PR to contribute
> > > to the devportal too, right?
> > 
> > Yes, you're right, but I think the process for github is intuitive,
> > and the contributor does not work with commandline (was my main
> > point).
> > 
> > Pagure needs require FAS though, right? What are the ACLs? Can anyone
> > open a PR? The process seems a bit more complicated, and I'm not sure
> > how many people already have github account, compared to FAS (does any
> > of them support oauth from 3rd party? I'm unsure).
>
> As far as I know, only FAS is enabled for pagure.io. I *think* that's
> intentional, though---it allows integration with the rest of Fedora over
> fedora-messaging and so on. A mirror of the repo on Pagure for PRs over
> GitHub can always be maintained. Lots of projects already do it. Fpaste
> is an example:
>
> https://pagure.io/fpaste
> https://github.com/sanjayankur31/fpaste

Good idea. Having only FAS would hopefully be fine as well.
> Anyone with an account on Pagure can open PRs. One can define groups for
> access etc., pretty much the same as on GitHub.
> > > > Unfortunately, I don't have any spare cycles to do anything like that
> > > > (I don't have much for the maintenance either).
> > >
> > > I think that's another reason to merge it with docs, which will be
> > > managed by the community, both infrastructure and content wise.
> >
> > Agreed. Well, if it migrates well :), anyway.
> >
> > IMO the UX seems a lot friendlier with Developer Portal, with several
> > overviews, and it's also more granular (more sub-pages). Is there such
> > feature (or a limit) in quick-docs? Also, there's no search (which
> > limits the usability for me at least).
>
> I'm afraid I don't know all the features of the Antora based system, so
> someone from the Docs core team will have to chime in here.
>
> The search function is high on the TODO list. I think @mattdm has spoken
> to CPE about this too, so it's not too far on the horizon.

Good to hear some work is being done!
> https://pagure.io/fedora-docs/docs-fp-o/issue/2
> https://pagure.io/fedora-infrastructure/issue/6750
> > I don't want to end up with few monolithic pages noone reads. (And
> > it's aimed at developers, so english is almost natural I expect.)
>
> Is there any information on how many people are reading the dev portal
> now? We know lots of people are using the Docs now, and we are

I was not sure where to post this- I hope this is sufficient:
  https://www.smugmug.com/gallery/n-QhFMkH/

There's a download button if you don't like the view. Also let me know if you want to know more / some other statistics.

How does this compare to quick-docs?
> frequently helping new folks write more quick-docs (over at Ask Fedora,
> for example). We're using it as a gateway to contribution---lots of
> users who tinker with their systems are happy to share their knowledge,
> so we help them write new quick-docs on their topic of choice.

Right, that's the same as for Developer Portal.
> > We could duplicate the content, however (for a while) and see how it
> > compares, if you insist. Some automated translation (mirroring) would
> > be a win-win IMO. Though I'm unsure it can be done.
>
> I am not insisting at all. I am only wondering if it makes sense to have
> another platform with information that the Docs are already designed to
> hold. It splits the resources, and it makes users wonder where they
> should look for information.

Well, it makes sense to move to another platform, if its use is better for some users. I can only speak for myself, but currently I like the portal a bit more. At this point there're not much resources (on the maintainers side), but the users may be confused (it depends). I can see the aim you're going for, but I'm still unsure there's a case for something to just cease existing, unless being replaced by something superior.
> I don't think temporarily duplicating information is a good way to go.
> That just makes it two copies that need to be updated then. If an

I'm more on the "can mirroring be done?" for that (I'd consider it "another view" for the content). I don't want to do a manual syncs off course. But for start, I was thinking about doing it in some staging quick-docs instance and try to see how it would compare the current F. D. Portal, as a one-off.
> agreement cannot be reached to migrate the info into Docs, I think it's
> best to leave things as they are. The Docs team keeps working on the
> Docs, and the Devportal team can keep working away there.
>
> As a community member, I thought I'd ask. That's all :)

Sorry, I didn't mean to send / dismiss you away, or to generally disagree. I was just playing a "devil's advocate" for the status quo, by raising some of the unanswered questions I have. There can be solution off course, I didn't mean to say otherwise, but I'm still unsure who / how / to what end would the migration effort aim. Currently, there's scarcely any work being done on the Developer portal, so the migration would need investigated & realized by some other community member(s).

Also, I know that's not the intention, but I'm treading carefully as I don't think we want to lose the current audience. Although the updates are currently stuck, with some spare cycles[*] that'll be resolved, ETA at the end of February.

Best regards,
Pavel

* Not much, there's automation already in place - I need to revive an old VM for the builds. Also some work was already done for the move into OpenShift, which was unfortunatelly disrupted leading to current state.
> --
> Thanks,
> Regards,
> Ankur Sinha "FranciscoD" (He / Him / His) |
> https://fedoraproject.org/wiki/User:Ankursinha
> Time zone: Europe/London