Hi All,
As some of you may be aware there has been chatter around having the documentation for infrastructure and release engineering centralised in one place.
A possible solution to this is to move all of these under a new section on docs.fedoraproject.org called something like Infrastructure and Release Engineering (very original I know).
We could then go about moving docs which are suitable from currrent locations to the new central point. Each doc should be updated before moving and the old document should be updated to only contain a link to the new doc to avoid a case of multiple versions of a doc (https://xkcd.com/927/ ).
The following links contain the bulk of the documentation:
https://fedora-infra-docs.readthedocs.io/en/latest/ https://docs.pagure.org/releng/ https://fedoraproject.org/wiki/Infrastructure
These would be the suggested first steps with other docs to follow if/when these are completed.
As I say this is just a possible solution so as always all feedback and suggestions are encouraged and welcomed.
Thanks, Mark
On Tue, May 04, 2021 at 04:49:43PM +0100, Mark O'Brien wrote:
Hi All,
As some of you may be aware there has been chatter around having the documentation for infrastructure and release engineering centralised in one place.
A possible solution to this is to move all of these under a new section on docs.fedoraproject.org called something like Infrastructure and Release Engineering (very original I know).
Sounds good to me. :)
We could then go about moving docs which are suitable from currrent locations to the new central point. Each doc should be updated before moving and the old document should be updated to only contain a link to the new doc to avoid a case of multiple versions of a doc (https://xkcd.com/927/ ).
The following links contain the bulk of the documentation:
https://fedora-infra-docs.readthedocs.io/en/latest/ https://docs.pagure.org/releng/ https://fedoraproject.org/wiki/Infrastructure
These would be the suggested first steps with other docs to follow if/when these are completed.
As I say this is just a possible solution so as always all feedback and suggestions are encouraged and welcomed.
I think it's a good idea to centralize them like this.
Some things are kind of hazy if they are Infrastructure or Release engineering, but otherwise I think the two areas could go well together.
Probibly the first thing we should do is work on moving and reworking the contribution/getting started stuff out of the wiki and into docs. :)
Then, perhaps it might make sense to do a pass and mark/note all the docs we want to just drop (no longer relevent, etc).
Thanks for working on this!
kevin
I think it's a good idea to centralize them like this.
Some things are kind of hazy if they are Infrastructure or Release engineering, but otherwise I think the two areas could go well together.
Probibly the first thing we should do is work on moving and reworking the contribution/getting started stuff out of the wiki and into docs. :)
This would be a good starting point as it is possibly our most important doc.
Then, perhaps it might make sense to do a pass and mark/note all the docs we want to just drop (no longer relevent, etc).
The bulk of the work would be in this task I imagine, between deciding what we don't need and rewriting what is out of date.
Thanks for working on this!
kevin
Count me in. I'm keen to help out with this initiative!
cheers, ryanlerch
On Wed, May 5, 2021 at 7:44 PM Mark O'Brien markobri@redhat.com wrote:
I think it's a good idea to centralize them like this.
Some things are kind of hazy if they are Infrastructure or Release engineering, but otherwise I think the two areas could go well together.
Probibly the first thing we should do is work on moving and reworking the contribution/getting started stuff out of the wiki and into docs. :)
This would be a good starting point as it is possibly our most important doc.
Then, perhaps it might make sense to do a pass and mark/note all the docs we want to just drop (no longer relevent, etc).
The bulk of the work would be in this task I imagine, between deciding what we don't need and rewriting what is out of date.
Thanks for working on this!
kevin
infrastructure mailing list -- infrastructure@lists.fedoraproject.org To unsubscribe send an email to infrastructure-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/infrastructure@lists.fedorapro... Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
One approach here would be to have several repos (i.e. documents). For example, we could break up this document: https://fedora-infra-docs.readthedocs.io/en/latest/ into
* Fedora Infra Developers Guide * Fedora Infra Sysadmin's Guide (i.e. the SOPs)
We would probably have to create a new section on this page: https://docs.fedoraproject.org/en-US/docs/ There is an "Engineering Teams" section that contains a couple links to our docs (https://docs.fedoraproject.org/en-US/engineering/) but a whole separate category on the main page is probably a good idea here IMHO.
This new section would probably list documents like the newish Fedora Accounts document (https://docs.fedoraproject.org/en-US/fedora-accounts/) and any other user-facing documents about our apps too.
For the structure of the sources, something simple like repos labelled "Documentation" in the fedora-infra github org might be the way to go, like the source for the Fedora Accounts docs: https://github.com/search?q=topic%3Adocumentation+org%3Afedora-infra&typ...
cheers, ryanlerch
On Wed, May 5, 2021 at 9:49 PM Ryan Lerch rlerch@redhat.com wrote:
Count me in. I'm keen to help out with this initiative!
cheers, ryanlerch
On Wed, May 5, 2021 at 7:44 PM Mark O'Brien markobri@redhat.com wrote:
I think it's a good idea to centralize them like this.
Some things are kind of hazy if they are Infrastructure or Release engineering, but otherwise I think the two areas could go well together.
Probibly the first thing we should do is work on moving and reworking the contribution/getting started stuff out of the wiki and into docs. :)
This would be a good starting point as it is possibly our most important doc.
Then, perhaps it might make sense to do a pass and mark/note all the docs we want to just drop (no longer relevent, etc).
The bulk of the work would be in this task I imagine, between deciding what we don't need and rewriting what is out of date.
Thanks for working on this!
kevin
infrastructure mailing list -- infrastructure@lists.fedoraproject.org To unsubscribe send an email to infrastructure-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/infrastructure@lists.fedorapro... Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
So thanks from some awesome hard work from @mkonecny, @asaleh, @dkirwan, @mobrien, and @nirik all the existing SOPs have been imported into the new docs.fedoraproject.org repository [1] and can be viewed on docs.fedoraproject.org [2].
The next step for the docs are to fully review the content of each SOP to ensure that it is still correct. (many of the SOPs refer to FAS2 and other things, and clearly need to be rewritten) For this step, i have created tickets for each SOP [3] and have tagged all of them as untraiged -- if they do require a re-write, i am going to tag it as such, otherwise if the SOP looks valid -- will close the ticket with a comment.
Finally, should we alos consider now removing / archiving the other 2 places this content is living (the sphinx output on readthedocs and pagure docs) so there is no more confusion on where our docs live?
cheers, ryanlerch
[1] - https://pagure.io/infra-docs-fpo [2] - https://docs.fedoraproject.org/en-US/infra/sysadmin_guide/ [3] - https://pagure.io/infra-docs-fpo/issues
On Mon, May 17, 2021 at 1:10 PM Ryan Lerch rlerch@redhat.com wrote:
One approach here would be to have several repos (i.e. documents). For example, we could break up this document: https://fedora-infra-docs.readthedocs.io/en/latest/ into
- Fedora Infra Developers Guide
- Fedora Infra Sysadmin's Guide (i.e. the SOPs)
We would probably have to create a new section on this page: https://docs.fedoraproject.org/en-US/docs/ There is an "Engineering Teams" section that contains a couple links to our docs (https://docs.fedoraproject.org/en-US/engineering/) but a whole separate category on the main page is probably a good idea here IMHO.
This new section would probably list documents like the newish Fedora Accounts document (https://docs.fedoraproject.org/en-US/fedora-accounts/) and any other user-facing documents about our apps too.
For the structure of the sources, something simple like repos labelled "Documentation" in the fedora-infra github org might be the way to go, like the source for the Fedora Accounts docs: https://github.com/search?q=topic%3Adocumentation+org%3Afedora-infra&typ...
cheers, ryanlerch
On Wed, May 5, 2021 at 9:49 PM Ryan Lerch rlerch@redhat.com wrote:
Count me in. I'm keen to help out with this initiative!
cheers, ryanlerch
On Wed, May 5, 2021 at 7:44 PM Mark O'Brien markobri@redhat.com wrote:
I think it's a good idea to centralize them like this.
Some things are kind of hazy if they are Infrastructure or Release engineering, but otherwise I think the two areas could go well together.
Probibly the first thing we should do is work on moving and reworking the contribution/getting started stuff out of the wiki and into docs. :)
This would be a good starting point as it is possibly our most important doc.
Then, perhaps it might make sense to do a pass and mark/note all the docs we want to just drop (no longer relevent, etc).
The bulk of the work would be in this task I imagine, between deciding what we don't need and rewriting what is out of date.
Thanks for working on this!
kevin
infrastructure mailing list -- infrastructure@lists.fedoraproject.org To unsubscribe send an email to infrastructure-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/infrastructure@lists.fedorapro... Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
On Tue, Nov 9, 2021 at 9:39 AM Ryan Lerch rlerch@redhat.com wrote:
So thanks from some awesome hard work from @mkonecny, @asaleh, @dkirwan, @mobrien, and @nirik all the existing SOPs have been imported into the new docs.fedoraproject.org repository [1] and can be viewed on docs.fedoraproject.org [2].
The next step for the docs are to fully review the content of each SOP to ensure that it is still correct. (many of the SOPs refer to FAS2 and other things, and clearly need to be rewritten) For this step, i have created tickets for each SOP [3] and have tagged all of them as untraiged -- if they do require a re-write, i am going to tag it as such, otherwise if the SOP looks valid -- will close the ticket with a comment.
Finally, should we alos consider now removing / archiving the other 2 places this content is living (the sphinx output on readthedocs and pagure docs) so there is no more confusion on where our docs live?
On this point i saw that the developer guide hadnt been ported over to the new asciidoc repo for docs.fp.o, so i did that porting, and the PR is here:
https://pagure.io/infra-docs-fpo/pull-request/134
that appears to be the last of the content on that old repo.
cheers, ryanlerch
cheers, ryanlerch
[1] - https://pagure.io/infra-docs-fpo [2] - https://docs.fedoraproject.org/en-US/infra/sysadmin_guide/ [3] - https://pagure.io/infra-docs-fpo/issues
On Mon, May 17, 2021 at 1:10 PM Ryan Lerch rlerch@redhat.com wrote:
One approach here would be to have several repos (i.e. documents). For example, we could break up this document: https://fedora-infra-docs.readthedocs.io/en/latest/ into
- Fedora Infra Developers Guide
- Fedora Infra Sysadmin's Guide (i.e. the SOPs)
We would probably have to create a new section on this page: https://docs.fedoraproject.org/en-US/docs/ There is an "Engineering Teams" section that contains a couple links to our docs (https://docs.fedoraproject.org/en-US/engineering/) but a whole separate category on the main page is probably a good idea here IMHO.
This new section would probably list documents like the newish Fedora Accounts document (https://docs.fedoraproject.org/en-US/fedora-accounts/) and any other user-facing documents about our apps too.
For the structure of the sources, something simple like repos labelled "Documentation" in the fedora-infra github org might be the way to go, like the source for the Fedora Accounts docs: https://github.com/search?q=topic%3Adocumentation+org%3Afedora-infra&typ...
cheers, ryanlerch
On Wed, May 5, 2021 at 9:49 PM Ryan Lerch rlerch@redhat.com wrote:
Count me in. I'm keen to help out with this initiative!
cheers, ryanlerch
On Wed, May 5, 2021 at 7:44 PM Mark O'Brien markobri@redhat.com wrote:
I think it's a good idea to centralize them like this.
Some things are kind of hazy if they are Infrastructure or Release engineering, but otherwise I think the two areas could go well together.
Probibly the first thing we should do is work on moving and reworking the contribution/getting started stuff out of the wiki and into docs. :)
This would be a good starting point as it is possibly our most important doc.
Then, perhaps it might make sense to do a pass and mark/note all the docs we want to just drop (no longer relevent, etc).
The bulk of the work would be in this task I imagine, between deciding what we don't need and rewriting what is out of date.
Thanks for working on this!
kevin
infrastructure mailing list -- infrastructure@lists.fedoraproject.org To unsubscribe send an email to infrastructure-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/infrastructure@lists.fedorapro... Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
This is awesome thanks folks!
On Tue, 9 Nov 2021 at 09:31, Ryan Lerch rlerch@redhat.com wrote:
On Tue, Nov 9, 2021 at 9:39 AM Ryan Lerch rlerch@redhat.com wrote:
So thanks from some awesome hard work from @mkonecny, @asaleh, @dkirwan, @mobrien, and @nirik all the existing SOPs have been imported into the new docs.fedoraproject.org repository [1] and can be viewed on docs.fedoraproject.org [2].
The next step for the docs are to fully review the content of each SOP to ensure that it is still correct. (many of the SOPs refer to FAS2 and other things, and clearly need to be rewritten) For this step, i have created tickets for each SOP [3] and have tagged all of them as untraiged -- if they do require a re-write, i am going to tag it as such, otherwise if the SOP looks valid -- will close the ticket with a comment.
Finally, should we alos consider now removing / archiving the other 2 places this content is living (the sphinx output on readthedocs and pagure docs) so there is no more confusion on where our docs live?
On this point i saw that the developer guide hadnt been ported over to the new asciidoc repo for docs.fp.o, so i did that porting, and the PR is here:
https://pagure.io/infra-docs-fpo/pull-request/134
that appears to be the last of the content on that old repo.
cheers, ryanlerch
cheers, ryanlerch
[1] - https://pagure.io/infra-docs-fpo [2] - https://docs.fedoraproject.org/en-US/infra/sysadmin_guide/ [3] - https://pagure.io/infra-docs-fpo/issues
On Mon, May 17, 2021 at 1:10 PM Ryan Lerch rlerch@redhat.com wrote:
One approach here would be to have several repos (i.e. documents). For example, we could break up this document: https://fedora-infra-docs.readthedocs.io/en/latest/ into
- Fedora Infra Developers Guide
- Fedora Infra Sysadmin's Guide (i.e. the SOPs)
We would probably have to create a new section on this page: https://docs.fedoraproject.org/en-US/docs/ There is an "Engineering Teams" section that contains a couple links to our docs (https://docs.fedoraproject.org/en-US/engineering/) but a whole separate category on the main page is probably a good idea here IMHO.
This new section would probably list documents like the newish Fedora Accounts document (https://docs.fedoraproject.org/en-US/fedora-accounts/) and any other user-facing documents about our apps too.
For the structure of the sources, something simple like repos labelled "Documentation" in the fedora-infra github org might be the way to go, like the source for the Fedora Accounts docs:
https://github.com/search?q=topic%3Adocumentation+org%3Afedora-infra&typ...
cheers, ryanlerch
On Wed, May 5, 2021 at 9:49 PM Ryan Lerch rlerch@redhat.com wrote:
Count me in. I'm keen to help out with this initiative!
cheers, ryanlerch
On Wed, May 5, 2021 at 7:44 PM Mark O'Brien markobri@redhat.com
wrote:
I think it's a good idea to centralize them like this.
Some things are kind of hazy if they are Infrastructure or Release engineering, but otherwise I think the two areas could go well
together.
Probibly the first thing we should do is work on moving and
reworking
the contribution/getting started stuff out of the wiki and into
docs. :)
This would be a good starting point as it is possibly our most
important doc.
Then, perhaps it might make sense to do a pass and mark/note all
the
docs we want to just drop (no longer relevent, etc).
The bulk of the work would be in this task I imagine, between
deciding
what we don't need and rewriting what is out of date.
Thanks for working on this!
kevin
infrastructure mailing list --
infrastructure@lists.fedoraproject.org
To unsubscribe send an email to
infrastructure-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/infrastructure@lists.fedorapro...
Do not reply to spam on the list, report it:
https://pagure.io/fedora-infrastructure _______________________________________________ infrastructure mailing list -- infrastructure@lists.fedoraproject.org To unsubscribe send an email to infrastructure-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/infrastructure@lists.fedorapro... Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
So the trackers are now closed on:
and the docs hosted on there now have a link and html redirect to the new docs.fp.o site:
https://docs.pagure.org/infra-docs/
I dont have access to remove or add redirects for the readthedocs site here, so that is still up:
https://fedora-infra-docs.readthedocs.io/en/latest/
cheers, ryanlerch
On Tue, Nov 9, 2021 at 7:29 PM Ryan Lerch rlerch@redhat.com wrote:
On Tue, Nov 9, 2021 at 9:39 AM Ryan Lerch rlerch@redhat.com wrote:
So thanks from some awesome hard work from @mkonecny, @asaleh, @dkirwan, @mobrien, and @nirik all the existing SOPs have been imported into the new docs.fedoraproject.org repository [1] and can be viewed on docs.fedoraproject.org [2].
The next step for the docs are to fully review the content of each SOP to ensure that it is still correct. (many of the SOPs refer to FAS2 and other things, and clearly need to be rewritten) For this step, i have created tickets for each SOP [3] and have tagged all of them as untraiged -- if they do require a re-write, i am going to tag it as such, otherwise if the SOP looks valid -- will close the ticket with a comment.
Finally, should we alos consider now removing / archiving the other 2 places this content is living (the sphinx output on readthedocs and pagure docs) so there is no more confusion on where our docs live?
On this point i saw that the developer guide hadnt been ported over to the new asciidoc repo for docs.fp.o, so i did that porting, and the PR is here:
https://pagure.io/infra-docs-fpo/pull-request/134
that appears to be the last of the content on that old repo.
cheers, ryanlerch
cheers, ryanlerch
[1] - https://pagure.io/infra-docs-fpo [2] - https://docs.fedoraproject.org/en-US/infra/sysadmin_guide/ [3] - https://pagure.io/infra-docs-fpo/issues
On Mon, May 17, 2021 at 1:10 PM Ryan Lerch rlerch@redhat.com wrote:
One approach here would be to have several repos (i.e. documents). For example, we could break up this document: https://fedora-infra-docs.readthedocs.io/en/latest/ into
- Fedora Infra Developers Guide
- Fedora Infra Sysadmin's Guide (i.e. the SOPs)
We would probably have to create a new section on this page: https://docs.fedoraproject.org/en-US/docs/ There is an "Engineering Teams" section that contains a couple links to our docs (https://docs.fedoraproject.org/en-US/engineering/) but a whole separate category on the main page is probably a good idea here IMHO.
This new section would probably list documents like the newish Fedora Accounts document (https://docs.fedoraproject.org/en-US/fedora-accounts/) and any other user-facing documents about our apps too.
For the structure of the sources, something simple like repos labelled "Documentation" in the fedora-infra github org might be the way to go, like the source for the Fedora Accounts docs: https://github.com/search?q=topic%3Adocumentation+org%3Afedora-infra&typ...
cheers, ryanlerch
On Wed, May 5, 2021 at 9:49 PM Ryan Lerch rlerch@redhat.com wrote:
Count me in. I'm keen to help out with this initiative!
cheers, ryanlerch
On Wed, May 5, 2021 at 7:44 PM Mark O'Brien markobri@redhat.com wrote:
I think it's a good idea to centralize them like this.
Some things are kind of hazy if they are Infrastructure or Release engineering, but otherwise I think the two areas could go well together.
Probibly the first thing we should do is work on moving and reworking the contribution/getting started stuff out of the wiki and into docs. :)
This would be a good starting point as it is possibly our most important doc.
Then, perhaps it might make sense to do a pass and mark/note all the docs we want to just drop (no longer relevent, etc).
The bulk of the work would be in this task I imagine, between deciding what we don't need and rewriting what is out of date.
Thanks for working on this!
kevin
infrastructure mailing list -- infrastructure@lists.fedoraproject.org To unsubscribe send an email to infrastructure-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/infrastructure@lists.fedorapro... Do not reply to spam on the list, report it: https://pagure.io/fedora-infrastructure
infrastructure@lists.fedoraproject.org
-
David Kirwan -
Kevin Fenzi -
Mark O'Brien -
Ryan Lerch