3:32 p.m.
Hello all,
We currently have a lot of documentation in the Fedora Wiki[0][1]
that is either old and out of date or just not relevant anymore and I
know many people don't like to work in the wiki so I would like to
make a proposal to change the documentation workflow so that we can
improve the docs for ourselves and for potentially new community
contributors who would like to join the fun.
I would first like to explain a couple options I have about Release
Engineering documentation first.
I believe we should ultimately have two "types" of documentation for
different roles that contributors would like to take on.
I think we can define this as "Rel-Eng Ops" and "Rel-Eng Tools Devs"
such that:
Rel-Eng Ops are those who are doing the work to create composes,
manage the infrastructure, the day to day operations, and the like.
This is where the Standard Operating Procedures[1] for Fedora Release
Engineering should live as well as an on-boarding guide for new
community members who would like to know more about Fedora Rel-Eng
and/or join the group and share in the work.
Rel-Eng Tools Devs are people who are going to be collaborating on
release tools upstream such as pungi, mash, mock, koji, and others.
These tools should each independently have their own documentation and
test suites in order to describe how community developers who would
like to contribute to these tools can do so. Things here that should
be documented are common development workflows, tools that are used to
make development/contribution easier, coding guidelines, contribution
and pull request workflow guidelines, etc.
I think the tools themselves should be referenced in the SOPs or
"Rel-Eng Ops" documentation in order to bridge those who are using the
tools to the tools themselves as someone participating in one form of
contribution (working on Ops tasks) may very well also participate in
the other (contributing code to tools) or vice versa. I definitely
don't want there to be any impression that these should be disjoint
types of contribution/contributors but more so that they can stand on
their own independently if someone out in the community who would like
to contribute is more interested in one area versus the other.
Proposal:
I would like to start with the RelEng Ops documentation as it's the
most "single point of entry", has a lot of docs that can be
"translated" from the Wiki along with getting updates, and would be a
good resource to have updated and documented in terms of the
on-boarding of potential new contributors which could lead to interest
in other tools that need individual documentation.
We would format all documentation using ReStructuredText[2] and
sphinx-doc[3] as that is the defacto standard in the python community
(which most of our tooling is written in), it's easy to use, and is
already in use by the Fedora Apps, Infrastructure, and QA teams.
(There are more example but I thought these were enough)
I propose these docs live in the releng pagure repository
(https://pagure.io/releng) and possibly have a space on
readthedocs.org[4] as it's already under heavy use with Fedora
projects with docs written in rst/sphinx.[5][6][7][8][9]
We could alternatively use pagure itself for docs hosting as pagure
hosts it's own docs also written in sphinx[10][11][12], it's not as
automatic for rendering and would take a little bit of scripting but
it's certainly an option.
If you've made it this far you get a cookie or something, but thank
you for sticking with it.
I'm open to questions, comments, general feedback, and of course snide remarks.
Thank you,
-AdamM
[0] - https://fedoraproject.org/wiki/ReleaseEngineering
[1] -
https://fedoraproject.org/wiki/Category:Release_Engineering_SOPs?rd=Relea...
[2] - https://en.wikipedia.org/wiki/ReStructuredText
[3] - http://sphinx-doc.org/
[4] - https://readthedocs.org/
[5] - https://fedora-fedmsg.readthedocs.org/en/latest/
[6] - http://autocloud.readthedocs.org/en/latest/
[7] - http://fedimg.readthedocs.org/en/stable/
[8] - http://nuancier-lite.readthedocs.org/en/latest/
[9] - http://libtaskotron.readthedocs.org/en/latest/
[10] - https://pagure.io/pagure/blob/master/f/doc
[11] - https://pagure.io/docs/pagure/
[12] - https://docs.pagure.org/pagure/
10:14 a.m.
On Fri, Oct 09, 2015 at 03:32:15PM -0500, Adam Miller wrote:
Hello all,
We currently have a lot of documentation in the Fedora Wiki[0][1]
that is either old and out of date or just not relevant anymore and I
know many people don't like to work in the wiki so I would like to
make a proposal to change the documentation workflow so that we can
improve the docs for ourselves and for potentially new community
contributors who would like to join the fun.
I would first like to explain a couple options I have about Release
Engineering documentation first.
I believe we should ultimately have two "types" of documentation for
different roles that contributors would like to take on.
I think we can define this as "Rel-Eng Ops" and "Rel-Eng Tools Devs"
such that:
Rel-Eng Ops are those who are doing the work to create composes,
manage the infrastructure, the day to day operations, and the like.
This is where the Standard Operating Procedures[1] for Fedora Release
Engineering should live as well as an on-boarding guide for new
community members who would like to know more about Fedora Rel-Eng
and/or join the group and share in the work.
Rel-Eng Tools Devs are people who are going to be collaborating on
release tools upstream such as pungi, mash, mock, koji, and others.
These tools should each independently have their own documentation and
test suites in order to describe how community developers who would
like to contribute to these tools can do so. Things here that should
be documented are common development workflows, tools that are used to
make development/contribution easier, coding guidelines, contribution
and pull request workflow guidelines, etc.
I think the tools themselves should be referenced in the SOPs or
"Rel-Eng Ops" documentation in order to bridge those who are using the
tools to the tools themselves as someone participating in one form of
contribution (working on Ops tasks) may very well also participate in
the other (contributing code to tools) or vice versa. I definitely
don't want there to be any impression that these should be disjoint
types of contribution/contributors but more so that they can stand on
their own independently if someone out in the community who would like
to contribute is more interested in one area versus the other.
Proposal:
I would like to start with the RelEng Ops documentation as it's the
most "single point of entry", has a lot of docs that can be
"translated" from the Wiki along with getting updates, and would be a
good resource to have updated and documented in terms of the
on-boarding of potential new contributors which could lead to interest
in other tools that need individual documentation.
We would format all documentation using ReStructuredText[2] and
sphinx-doc[3] as that is the defacto standard in the python community
(which most of our tooling is written in), it's easy to use, and is
already in use by the Fedora Apps, Infrastructure, and QA teams.
(There are more example but I thought these were enough)
I propose these docs live in the releng pagure repository
(https://pagure.io/releng) and possibly have a space on
readthedocs.org[4] as it's already under heavy use with Fedora
projects with docs written in rst/sphinx.[5][6][7][8][9]
We could alternatively use pagure itself for docs hosting as pagure
hosts it's own docs also written in sphinx[10][11][12], it's not as
automatic for rendering and would take a little bit of scripting but
it's certainly an option.
If you've made it this far you get a cookie or something, but thank
you for sticking with it.
I'm open to questions, comments, general feedback, and of course
snide remarks.
Minor technical point, but do or Pierre think it's possible to
integrate readthedocs functionality with Pagure, such that a push to
your Sphinx docs would regenerate the site there?
Obviously readthedocs is itself FOSS so perhaps we could contribute a
patch for this upstream, since it seems like it's at least partly a
function of that site.
--
Paul W. Frields http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - - http://pfrields.fedorapeople.org/
The open source story continues to grow: http://opensource.com
11:18 a.m.
On Oct 16, 2015 10:14 AM, "Paul W. Frields" <stickster(a)gmail.com> wrote:
On Fri, Oct 09, 2015 at 03:32:15PM -0500, Adam Miller wrote:
> Hello all,
> We currently have a lot of documentation in the Fedora Wiki[0][1]
> that is either old and out of date or just not relevant anymore and I
> know many people don't like to work in the wiki so I would like to
> make a proposal to change the documentation workflow so that we can
> improve the docs for ourselves and for potentially new community
> contributors who would like to join the fun.
>
> I would first like to explain a couple options I have about Release
> Engineering documentation first.
>
> I believe we should ultimately have two "types" of documentation for
> different roles that contributors would like to take on.
>
> I think we can define this as "Rel-Eng Ops" and "Rel-Eng Tools
Devs"
such that:
>
> Rel-Eng Ops are those who are doing the work to create composes,
> manage the infrastructure, the day to day operations, and the like.
> This is where the Standard Operating Procedures[1] for Fedora Release
> Engineering should live as well as an on-boarding guide for new
> community members who would like to know more about Fedora Rel-Eng
> and/or join the group and share in the work.
>
> Rel-Eng Tools Devs are people who are going to be collaborating on
> release tools upstream such as pungi, mash, mock, koji, and others.
> These tools should each independently have their own documentation and
> test suites in order to describe how community developers who would
> like to contribute to these tools can do so. Things here that should
> be documented are common development workflows, tools that are used to
> make development/contribution easier, coding guidelines, contribution
> and pull request workflow guidelines, etc.
>
> I think the tools themselves should be referenced in the SOPs or
> "Rel-Eng Ops" documentation in order to bridge those who are using the
> tools to the tools themselves as someone participating in one form of
> contribution (working on Ops tasks) may very well also participate in
> the other (contributing code to tools) or vice versa. I definitely
> don't want there to be any impression that these should be disjoint
> types of contribution/contributors but more so that they can stand on
> their own independently if someone out in the community who would like
> to contribute is more interested in one area versus the other.
>
> Proposal:
>
> I would like to start with the RelEng Ops documentation as it's the
> most "single point of entry", has a lot of docs that can be
> "translated" from the Wiki along with getting updates, and would be a
> good resource to have updated and documented in terms of the
> on-boarding of potential new contributors which could lead to interest
> in other tools that need individual documentation.
>
> We would format all documentation using ReStructuredText[2] and
> sphinx-doc[3] as that is the defacto standard in the python community
> (which most of our tooling is written in), it's easy to use, and is
> already in use by the Fedora Apps, Infrastructure, and QA teams.
> (There are more example but I thought these were enough)
>
> I propose these docs live in the releng pagure repository
> (https://pagure.io/releng) and possibly have a space on
> readthedocs.org[4] as it's already under heavy use with Fedora
> projects with docs written in rst/sphinx.[5][6][7][8][9]
>
> We could alternatively use pagure itself for docs hosting as pagure
> hosts it's own docs also written in sphinx[10][11][12], it's not as
> automatic for rendering and would take a little bit of scripting but
> it's certainly an option.
>
> If you've made it this far you get a cookie or something, but thank
> you for sticking with it.
>
> I'm open to questions, comments, general feedback, and of course
> snide remarks.
Minor technical point, but do or Pierre think it's possible to
integrate readthedocs functionality with Pagure, such that a push to
your Sphinx docs would regenerate the site there?
Obviously readthedocs is itself FOSS so perhaps we could contribute a
patch for this upstream, since it seems like it's at least partly a
function of that site.
--
Paul W. Frields
FWIW, the thing I'm putting together for docs.fp.o is intended to support
continuous delivery of documentation from git repos full of rst files. I
don't know if you want to wait for it, but when ready, we can simply add
some metadata to the articles (I did this for infra-docs already) and plug
the repo into the system.
--Pete
2:24 p.m.
On Fri, Oct 16, 2015 at 11:18:34AM -0500, Pete Travis wrote:
On Oct 16, 2015 10:14 AM, "Paul W. Frields"
<stickster(a)gmail.com> wrote:
>
> On Fri, Oct 09, 2015 at 03:32:15PM -0500, Adam Miller wrote:
> > Hello all,
> > We currently have a lot of documentation in the Fedora Wiki[0][1]
> > that is either old and out of date or just not relevant anymore and I
> > know many people don't like to work in the wiki so I would like to
> > make a proposal to change the documentation workflow so that we can
> > improve the docs for ourselves and for potentially new community
> > contributors who would like to join the fun.
> >
> > I would first like to explain a couple options I have about Release
> > Engineering documentation first.
> >
> > I believe we should ultimately have two "types" of documentation for
> > different roles that contributors would like to take on.
> >
> > I think we can define this as "Rel-Eng Ops" and "Rel-Eng Tools
Devs"
such that:
> >
> > Rel-Eng Ops are those who are doing the work to create composes,
> > manage the infrastructure, the day to day operations, and the like.
> > This is where the Standard Operating Procedures[1] for Fedora Release
> > Engineering should live as well as an on-boarding guide for new
> > community members who would like to know more about Fedora Rel-Eng
> > and/or join the group and share in the work.
> >
> > Rel-Eng Tools Devs are people who are going to be collaborating on
> > release tools upstream such as pungi, mash, mock, koji, and others.
> > These tools should each independently have their own documentation and
> > test suites in order to describe how community developers who would
> > like to contribute to these tools can do so. Things here that should
> > be documented are common development workflows, tools that are used to
> > make development/contribution easier, coding guidelines, contribution
> > and pull request workflow guidelines, etc.
> >
> > I think the tools themselves should be referenced in the SOPs or
> > "Rel-Eng Ops" documentation in order to bridge those who are using
the
> > tools to the tools themselves as someone participating in one form of
> > contribution (working on Ops tasks) may very well also participate in
> > the other (contributing code to tools) or vice versa. I definitely
> > don't want there to be any impression that these should be disjoint
> > types of contribution/contributors but more so that they can stand on
> > their own independently if someone out in the community who would like
> > to contribute is more interested in one area versus the other.
> >
> > Proposal:
> >
> > I would like to start with the RelEng Ops documentation as it's the
> > most "single point of entry", has a lot of docs that can be
> > "translated" from the Wiki along with getting updates, and would be
a
> > good resource to have updated and documented in terms of the
> > on-boarding of potential new contributors which could lead to interest
> > in other tools that need individual documentation.
> >
> > We would format all documentation using ReStructuredText[2] and
> > sphinx-doc[3] as that is the defacto standard in the python community
> > (which most of our tooling is written in), it's easy to use, and is
> > already in use by the Fedora Apps, Infrastructure, and QA teams.
> > (There are more example but I thought these were enough)
> >
> > I propose these docs live in the releng pagure repository
> > (https://pagure.io/releng) and possibly have a space on
> > readthedocs.org[4] as it's already under heavy use with Fedora
> > projects with docs written in rst/sphinx.[5][6][7][8][9]
> >
> > We could alternatively use pagure itself for docs hosting as pagure
> > hosts it's own docs also written in sphinx[10][11][12], it's not as
> > automatic for rendering and would take a little bit of scripting but
> > it's certainly an option.
> >
> > If you've made it this far you get a cookie or something, but thank
> > you for sticking with it.
> >
> > I'm open to questions, comments, general feedback, and of course
> > snide remarks.
>
> Minor technical point, but do or Pierre think it's possible to
> integrate readthedocs functionality with Pagure, such that a push to
> your Sphinx docs would regenerate the site there?
>
> Obviously readthedocs is itself FOSS so perhaps we could contribute a
> patch for this upstream, since it seems like it's at least partly a
> function of that site.
>
>
> --
> Paul W. Frields
FWIW, the thing I'm putting together for docs.fp.o is intended to support
continuous delivery of documentation from git repos full of rst files. I
don't know if you want to wait for it, but when ready, we can simply add
some metadata to the articles (I did this for infra-docs already) and plug
the repo into the system.
Pete, might be going OT for this list, in which case we can go
elsewhere, but how does that differ from readthedocs? I'm curious
what's missing there that might affect other places our team's using
it.
--
Paul W. Frields http://paul.frields.org/
gpg fingerprint: 3DA6 A0AC 6D58 FEC4 0233 5906 ACDB C937 BD11 3717
http://redhat.com/ - - - - http://pfrields.fedorapeople.org/
The open source story continues to grow: http://opensource.com
11:23 a.m.
On 10/16/2015 02:24 PM, Paul W. Frields wrote:
On Fri, Oct 16, 2015 at 11:18:34AM -0500, Pete Travis wrote:
> On Oct 16, 2015 10:14 AM, "Paul W. Frields" <stickster(a)gmail.com>
wrote:
>> On Fri, Oct 09, 2015 at 03:32:15PM -0500, Adam Miller wrote:
>>> Hello all,
>>> We currently have a lot of documentation in the Fedora Wiki[0][1]
>>> that is either old and out of date or just not relevant anymore and I
>>> know many people don't like to work in the wiki so I would like to
>>> make a proposal to change the documentation workflow so that we can
>>> improve the docs for ourselves and for potentially new community
>>> contributors who would like to join the fun.
>>>
>>> I would first like to explain a couple options I have about Release
>>> Engineering documentation first.
>>>
>>> I believe we should ultimately have two "types" of documentation
for
>>> different roles that contributors would like to take on.
>>>
>>> I think we can define this as "Rel-Eng Ops" and "Rel-Eng Tools
Devs"
> such that:
>>> Rel-Eng Ops are those who are doing the work to create composes,
>>> manage the infrastructure, the day to day operations, and the like.
>>> This is where the Standard Operating Procedures[1] for Fedora Release
>>> Engineering should live as well as an on-boarding guide for new
>>> community members who would like to know more about Fedora Rel-Eng
>>> and/or join the group and share in the work.
>>>
>>> Rel-Eng Tools Devs are people who are going to be collaborating on
>>> release tools upstream such as pungi, mash, mock, koji, and others.
>>> These tools should each independently have their own documentation and
>>> test suites in order to describe how community developers who would
>>> like to contribute to these tools can do so. Things here that should
>>> be documented are common development workflows, tools that are used to
>>> make development/contribution easier, coding guidelines, contribution
>>> and pull request workflow guidelines, etc.
>>>
>>> I think the tools themselves should be referenced in the SOPs or
>>> "Rel-Eng Ops" documentation in order to bridge those who are using
the
>>> tools to the tools themselves as someone participating in one form of
>>> contribution (working on Ops tasks) may very well also participate in
>>> the other (contributing code to tools) or vice versa. I definitely
>>> don't want there to be any impression that these should be disjoint
>>> types of contribution/contributors but more so that they can stand on
>>> their own independently if someone out in the community who would like
>>> to contribute is more interested in one area versus the other.
>>>
>>> Proposal:
>>>
>>> I would like to start with the RelEng Ops documentation as it's the
>>> most "single point of entry", has a lot of docs that can be
>>> "translated" from the Wiki along with getting updates, and would be
a
>>> good resource to have updated and documented in terms of the
>>> on-boarding of potential new contributors which could lead to interest
>>> in other tools that need individual documentation.
>>>
>>> We would format all documentation using ReStructuredText[2] and
>>> sphinx-doc[3] as that is the defacto standard in the python community
>>> (which most of our tooling is written in), it's easy to use, and is
>>> already in use by the Fedora Apps, Infrastructure, and QA teams.
>>> (There are more example but I thought these were enough)
>>>
>>> I propose these docs live in the releng pagure repository
>>> (https://pagure.io/releng) and possibly have a space on
>>> readthedocs.org[4] as it's already under heavy use with Fedora
>>> projects with docs written in rst/sphinx.[5][6][7][8][9]
>>>
>>> We could alternatively use pagure itself for docs hosting as pagure
>>> hosts it's own docs also written in sphinx[10][11][12], it's not as
>>> automatic for rendering and would take a little bit of scripting but
>>> it's certainly an option.
>>>
>>> If you've made it this far you get a cookie or something, but thank
>>> you for sticking with it.
>>>
>>> I'm open to questions, comments, general feedback, and of course
>>> snide remarks.
>> Minor technical point, but do or Pierre think it's possible to
>> integrate readthedocs functionality with Pagure, such that a push to
>> your Sphinx docs would regenerate the site there?
>>
>> Obviously readthedocs is itself FOSS so perhaps we could contribute a
>> patch for this upstream, since it seems like it's at least partly a
>> function of that site.
>>
>>
>> --
>> Paul W. Frields
> FWIW, the thing I'm putting together for docs.fp.o is intended to support
> continuous delivery of documentation from git repos full of rst files. I
> don't know if you want to wait for it, but when ready, we can simply add
> some metadata to the articles (I did this for infra-docs already) and plug
> the repo into the system.
Pete, might be going OT for this list, in which case we can go
elsewhere, but how does that differ from readthedocs? I'm curious
what's missing there that might affect other places our team's using
it.
Readthedocs gives you one site per resource, so you'd have ie
fedora-releng.readthedocs.org as one big book about fedora's release
engineering . I want to present many resources in a browseable way, so
this will also generate category pages, navigation structure, etc. The
goal is to put things like releng, apps, infra, qa docs in one place
where they can interlink, along with user facing docs of all types. The
goal is to offload *everyone's* publishing and formatting work to one
place, so you really only have to worry about content.
-- Pete
(reply to all fail, sorry for the noise, Paul)
3114
days inactive
3122
days old
rel-eng@lists.fedoraproject.org
4 comments
3 participants
participants (3)
-
Adam Miller -
Paul W. Frields -
Pete Travis