Proposal: Infrastructure Apps documentation project

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



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@xxxxxxxxxx
IRC:  jcline

Attachment: signature.asc
Description: OpenPGP digital signature

_______________________________________________
infrastructure mailing list -- infrastructure@xxxxxxxxxxxxxxxxxxxxxxx
To unsubscribe send an email to infrastructure-leave@xxxxxxxxxxxxxxxxxxxxxxx

[Index of Archives]     [Fedora Development]     [Fedora Users]     [Fedora Desktop]     [Fedora SELinux]     [Yosemite News]     [KDE Users]

  Powered by Linux