Hey all,
I've been mulling on this idea for a while, but Kushal's opensource.com[0] article last week has inspired me to make this proposal. I think it would be very nice if we had a documentation project that covered Fedora Infrastructure Applications as a whole. I envision it serving the following purposes:
* Provide an excellent "Getting started" guide for new developers.
* Cover the tools we use and the frameworks/libraries our projects frequently depend on (and why we chose them over alternatives). This is especially helpful for newer developers who might encounter a problem and not be aware there's a library or tool we regularly use that solves it.
* Gives us a place to decide on and document contribution guidelines that apply to all the projects we maintain.
* Provide a place to document common problems (and hopefully solutions) projects we work on face.
Some examples of things I would like to document:
* How to start a Sphinx docs project and use various extensions to generate Python API and REST API documentation automatically. It would also serve as a guide for new developers on docblock style(s) and features.
* A sample Flask project layout. This would serve to contain a lot of boilerplate (setup.py, test layout, etc) with various tips and tricks we all learn as we go.
Release Engineering has a project[1] similar to what I have in mind. I notice they have their SOPs built in this project and I think it would be great if we had all the Fedora Apps SOPs built into this project I'm proposing.
I'm relatively new here, and two of the challenges I've faced while getting up to speed is the lack of in-depth documentation for projects and the huge variance between projects in terms of style. We're a wide- spread team and everyone is working on several projects at once. I think if we make an effort to standardize a little bit (and document what will vary between the projects) it will make it much easier to get involved in our projects.
Overall, I think it would be a great place to learn from one another and would make getting involved much easier.
What do you all think?
[0] https://opensource.com/article/17/1/expand-project-contributor-base [1] https://docs.pagure.org/releng/
On Thu, 26 Jan 2017 09:53:20 -0500 Jeremy Cline jeremy@jcline.org wrote: ...snip...
Overall, I think it would be a great place to learn from one another and would make getting involved much easier.
What do you all think?
+100. I think more docs and on-boarding would be great.
The usual problem is that we just don't prioritize it, so it never gets done. ;(
kevin
Hey all,
I would be interested in assisting with that project.
Thanks, Joe
On Thu, Jan 26, 2017 at 12:26 PM, Kevin Fenzi kevin@scrye.com wrote:
On Thu, 26 Jan 2017 09:53:20 -0500 Jeremy Cline jeremy@jcline.org wrote: ...snip...
Overall, I think it would be a great place to learn from one another and would make getting involved much easier.
What do you all think?
+100. I think more docs and on-boarding would be great.
The usual problem is that we just don't prioritize it, so it never gets done. ;(
kevin
infrastructure mailing list -- infrastructure@lists.fedoraproject.org To unsubscribe send an email to infrastructure-leave@lists. fedoraproject.org
I think I have mentioned this in an infra-meeting, but we could use Pagure docs feature to host the infrastructure SOP. It would make them a little bit more user friendly and easier to access.
Regarding the development side, I have rediscovered recently the developer portal [0] and it looks great, but I don't think it is well known or used. For example there is some doc on how to start a flask project [1]
Maybe instead of rewriting an app from scratch we could use the developer portal.
Thanks Clement
[0] https://developer.fedoraproject.org [1] https://developer.fedoraproject.org/tech/languages/python/flask-installation...
26. Jan 2017 15:53 by jeremy@jcline.org:
Hey all,
I've been mulling on this idea for a while, but Kushal's opensource.com[0] article last week has inspired me to make this proposal. I think it would be very nice if we had a documentation project that covered Fedora Infrastructure Applications as a whole. I envision it serving the following purposes:
Provide an excellent "Getting started" guide for new developers.
Cover the tools we use and the frameworks/libraries our projects frequently depend on (and why we chose them over alternatives). This is especially helpful for newer developers who might encounter a problem and not be aware there's a library or tool we regularly use that solves it.
Gives us a place to decide on and document contribution guidelines that apply to all the projects we maintain.
Provide a place to document common problems (and hopefully solutions) projects we work on face.
Some examples of things I would like to document:
How to start a Sphinx docs project and use various extensions to generate Python API and REST API documentation automatically. It would also serve as a guide for new developers on docblock style(s) and features.
A sample Flask project layout. This would serve to contain a lot of boilerplate (setup.py, test layout, etc) with various tips and tricks we all learn as we go.
Release Engineering has a project[1] similar to what I have in mind. I notice they have their SOPs built in this project and I think it would be great if we had all the Fedora Apps SOPs built into this project I'm proposing.
I'm relatively new here, and two of the challenges I've faced while getting up to speed is the lack of in-depth documentation for projects and the huge variance between projects in terms of style. We're a wide- spread team and everyone is working on several projects at once. I think if we make an effort to standardize a little bit (and document what will vary between the projects) it will make it much easier to get involved in our projects.
Overall, I think it would be a great place to learn from one another and would make getting involved much easier.
What do you all think?
[0] > https://opensource.com/article/17/1/expand-project-contributor-base [1] > https://docs.pagure.org/releng
-- Jeremy Cline XMPP: > jeremy@jcline.org IRC: jcline
On 01/27/2017 07:19 AM, Clement Verna wrote:
I think I have mentioned this in an infra-meeting, but we could use Pagure docs feature to host the infrastructure SOP. It would make them a little bit more user friendly and easier to access.
My thinking was the SOPs would be a section of this documentation. Since showing is much easier than telling, I spent 20 minutes and sketched out (a bit) what I imagine this would look like: https://docs.pagure.org/infra-docs/
Regarding the development side, I have rediscovered recently the developer portal [0] and it looks great, but I don't think it is well known or used. For example there is some doc on how to start a flask project [1]
Maybe instead of rewriting an app from scratch we could use the developer portal.
I did not know about this at all, and it looks great! It seems like it's more general in a lot of areas than what I want, but I think we could using it as a starting off point or link directly to it in some cases.
On Fri, 27 Jan 2017 15:56:27 -0500 Jeremy Cline jeremy@jcline.org wrote:
On 01/27/2017 07:19 AM, Clement Verna wrote:
I think I have mentioned this in an infra-meeting, but we could use Pagure docs feature to host the infrastructure SOP. It would make them a little bit more user friendly and easier to access.
My thinking was the SOPs would be a section of this documentation. Since showing is much easier than telling, I spent 20 minutes and sketched out (a bit) what I imagine this would look like: https://docs.pagure.org/infra-docs/
Thats pretty awesome. The sops moved over better than I thought they would. :)
Regarding the development side, I have rediscovered recently the developer portal [0] and it looks great, but I don't think it is well known or used. For example there is some doc on how to start a flask project [1]
Maybe instead of rewriting an app from scratch we could use the developer portal.
I did not know about this at all, and it looks great! It seems like it's more general in a lot of areas than what I want, but I think we could using it as a starting off point or link directly to it in some cases.
I would very much like to not use the developer portal for our specific docs. Improving parts of it like the flask area, etc of course would be great.
It uses it's own framework that nothing else we have does (jekyll). It's not built in our infrastructure. (It builds from a github project and then that result is checked in and we pull that to serve it on our machines, which is pretty convoluted).
kevin
On Jan 27, 2017, at 10:09 PM, Kevin Fenzi kevin@scrye.com wrote:
On Fri, 27 Jan 2017 15:56:27 -0500 Jeremy Cline jeremy@jcline.org wrote:
On 01/27/2017 07:19 AM, Clement Verna wrote: I think I have mentioned this in an infra-meeting, but we could use Pagure docs feature to host the infrastructure SOP. It would make them a little bit more user friendly and easier to access.
My thinking was the SOPs would be a section of this documentation. Since showing is much easier than telling, I spent 20 minutes and sketched out (a bit) what I imagine this would look like: https://docs.pagure.org/infra-docs/
Thats pretty awesome. The sops moved over better than I thought they would. :)
Regarding the development side, I have rediscovered recently the developer portal [0] and it looks great, but I don't think it is well known or used. For example there is some doc on how to start a flask project [1]
Maybe instead of rewriting an app from scratch we could use the developer portal.
I did not know about this at all, and it looks great! It seems like it's more general in a lot of areas than what I want, but I think we could using it as a starting off point or link directly to it in some cases.
I would very much like to not use the developer portal for our specific docs. Improving parts of it like the flask area, etc of course would be great.
Wanna use the builder for the new budget infrastructure? It could also potentially host the docs.
Regards,
bex
It uses it's own framework that nothing else we have does (jekyll). It's not built in our infrastructure. (It builds from a github project and then that result is checked in and we pull that to serve it on our machines, which is pretty convoluted).
kevin _______________________________________________ infrastructure mailing list -- infrastructure@lists.fedoraproject.org To unsubscribe send an email to infrastructure-leave@lists.fedoraproject.org
On Sat, 28 Jan 2017 09:50:44 +0100 "Brian (bex) Exelbierd" bex@pobox.com wrote:
On Jan 27, 2017, at 10:09 PM, Kevin Fenzi kevin@scrye.com wrote:
On Fri, 27 Jan 2017 15:56:27 -0500 Jeremy Cline jeremy@jcline.org wrote:
On 01/27/2017 07:19 AM, Clement Verna wrote: I think I have mentioned this in an infra-meeting, but we could use Pagure docs feature to host the infrastructure SOP. It would make them a little bit more user friendly and easier to access.
My thinking was the SOPs would be a section of this documentation. Since showing is much easier than telling, I spent 20 minutes and sketched out (a bit) what I imagine this would look like: https://docs.pagure.org/infra-docs/
Thats pretty awesome. The sops moved over better than I thought they would. :)
Regarding the development side, I have rediscovered recently the developer portal [0] and it looks great, but I don't think it is well known or used. For example there is some doc on how to start a flask project [1]
Maybe instead of rewriting an app from scratch we could use the developer portal.
I did not know about this at all, and it looks great! It seems like it's more general in a lot of areas than what I want, but I think we could using it as a starting off point or link directly to it in some cases.
I would very much like to not use the developer portal for our specific docs. Improving parts of it like the flask area, etc of course would be great.
Wanna use the builder for the new budget infrastructure? It could also potentially host the docs.
I think pagure docs might be a better fit for this... we can then use the normal PR setup for changes, etc...
kevin
On Jan 30, 2017, at 7:03 PM, Kevin Fenzi kevin@scrye.com wrote:
On Sat, 28 Jan 2017 09:50:44 +0100 "Brian (bex) Exelbierd" bex@pobox.com wrote:
On Jan 27, 2017, at 10:09 PM, Kevin Fenzi kevin@scrye.com wrote:
On Fri, 27 Jan 2017 15:56:27 -0500 Jeremy Cline jeremy@jcline.org wrote:
On 01/27/2017 07:19 AM, Clement Verna wrote: I think I have mentioned this in an infra-meeting, but we could use Pagure docs feature to host the infrastructure SOP. It would make them a little bit more user friendly and easier to access.
My thinking was the SOPs would be a section of this documentation. Since showing is much easier than telling, I spent 20 minutes and sketched out (a bit) what I imagine this would look like: https://docs.pagure.org/infra-docs/
Thats pretty awesome. The sops moved over better than I thought they would. :)
Regarding the development side, I have rediscovered recently the developer portal [0] and it looks great, but I don't think it is well known or used. For example there is some doc on how to start a flask project [1]
Maybe instead of rewriting an app from scratch we could use the developer portal.
I did not know about this at all, and it looks great! It seems like it's more general in a lot of areas than what I want, but I think we could using it as a starting off point or link directly to it in some cases.
I would very much like to not use the developer portal for our specific docs. Improving parts of it like the flask area, etc of course would be great.
Wanna use the builder for the new budget infrastructure? It could also potentially host the docs.
I think pagure docs might be a better fit for this... we can then use the normal PR setup for changes, etc...
I'm happy for you to use the best tool for you. The process I am talking about is PR driven.
Regards,
bex
kevin _______________________________________________ infrastructure mailing list -- infrastructure@lists.fedoraproject.org To unsubscribe send an email to infrastructure-leave@lists.fedoraproject.org
Le 30 janvier 2017 20:12:45 UTC+01:00, "Brian (bex) Exelbierd" bex@pobox.com a écrit :
Wanna use the builder for the new budget infrastructure? It could also potentially host the docs.
I think pagure docs might be a better fit for this... we can then use the normal PR setup for changes, etc...
I'm happy for you to use the best tool for you. The process I am talking about is PR driven.
Regards,
bex
If possible, I would love to see the new documentation system used for this, in addition of the re-use of the tool chain and the documentation portal, some team may found the need for localization, and it would made this possible.
On 01/31/2017 01:15 PM, Jean-Baptiste Holcroft wrote:
If possible, I would love to see the new documentation system used for this, in addition of the re-use of the tool chain and the documentation portal, some team may found the need for localization, and it would made this possible.
I'm inclined to use Sphinx for several reasons. It's the go-to documentation tool for Python projects and so many people are already familiar with it. Additionally, we already use it heavily throughout our projects to document them.
Localization would be great, and is something a lot of our individual project documentation lacks. Sphinx has extensive internalization[0] support and we should use it. This would also be a good place to document how we use it and how our other Sphinx projects can use it.
[0] http://www.sphinx-doc.org/en/stable/intl.html
On 02/02/17, Jeremy Cline wrote:
On 01/31/2017 01:15 PM, Jean-Baptiste Holcroft wrote:
If possible, I would love to see the new documentation system used for this, in addition of the re-use of the tool chain and the documentation portal, some team may found the need for localization, and it would made this possible.
I'm inclined to use Sphinx for several reasons. It's the go-to documentation tool for Python projects and so many people are already familiar with it. Additionally, we already use it heavily throughout our projects to document them.
Go for it :). If you need any help, feel free to ping. Sphinx is also my favorite documentation tool.
Kushal
On Tue, Jan 31, 2017 at 07:15:59PM +0100, Jean-Baptiste Holcroft wrote:
Le 30 janvier 2017 20:12:45 UTC+01:00, "Brian (bex) Exelbierd" bex@pobox.com a écrit :
Wanna use the builder for the new budget infrastructure? It could also potentially host the docs.
I think pagure docs might be a better fit for this... we can then use the normal PR setup for changes, etc...
I'm happy for you to use the best tool for you. The process I am talking about is PR driven.
If possible, I would love to see the new documentation system used for this, in addition of the re-use of the tool chain and the documentation portal, some team may found the need for localization, and it would made this possible.
Well, the documentation we are talking about here are the internal procedures to follow in the infrastructure. They aren't really meant to be user-facing, much more a place for new comers to learn our procedures and for old-timers to find back "how do we do that again?". I do not think this documentation deserve being merged with the general documentation about Fedora, this is something that is really specific to this group and our setup. For this reason, I also think translations shouldn't be a priority. I wouldn't go against if someone wanted to translates these docs but I will also not encourage it very strongly :)
Just my thoughts though :)
Pierre
infrastructure@lists.fedoraproject.org
-
Brian Exelbierd -
Clement Verna -
Jean-Baptiste -
Jeremy Cline -
Joe Saunders -
Kevin Fenzi -
Kushal Das -
Pierre-Yves Chibon