Announcement

Collapse
No announcement yet.

Google Is Launching "Season of Docs" To Help Improve Open-Source Documentation

Collapse
X
  • Filter
  • Time
  • Show
Clear All
new posts

  • Google Is Launching "Season of Docs" To Help Improve Open-Source Documentation

    Phoronix: Google Is Launching "Season of Docs" To Help Improve Open-Source Documentation

    Google's Summer of Code is embarking on its 14th year of encouraging student developers to get involved with open-source development. Complementary to code contributions, Google is preparing its inaugural "Season of Docs" to help technical writers get involved in better preparing open-source program documentation...

    http://www.phoronix.com/scan.php?pag...Season-Of-Docs

  • #2
    That's actually a brilliant idea. Sorely needed. Some projects are severely lacking.

    Comment


    • #3
      No documentation method or system do help when developers will not tell everything. You need to read existing code and from implementation sources what some API really does. An example: https://dri.freedesktop.org/wiki/Con...ForDevelopers/

      Not a word that this API uses the process name to match a configuration.
      https://gitlab.freedesktop.org/mesa/...config.c#L1007

      This helped me to implement the radv adapative_sync blacklist system.
      Last edited by debianxfce; 04-14-2019, 03:58 AM.

      Comment


      • #4
        I wouldn't trust Google to clean my toilet. They'd get half way through and then quit.

        Comment


        • #5
          Qt is probably the project that needs this the least. But I guess even good documentation can get better.

          Comment


          • #6
            So doxygen is not enough? No way... /s

            Comment


            • #7
              So much negativity... I personally think this is a great idea. Even if nothing gets complete or they can't tackle anything too huge and complex, some documentation is better than none.

              Comment


              • #8
                Originally posted by schmidtbag View Post
                So much negativity... I personally think this is a great idea. Even if nothing gets complete or they can't tackle anything too huge and complex, some documentation is better than none.
                Yep. Software (library) is as good as it's useful.

                Even, if library is brilliant, without API documentation it is hard to use. And, worse libraries with documentation take over, just because other developers know how to use them.

                Comment


                • #9
                  Originally posted by kravemir View Post

                  Yep. Software (library) is as good as it's useful.

                  Even, if library is brilliant, without API documentation it is hard to use. And, worse libraries with documentation take over, just because other developers know how to use them.
                  I know that a lot of y'all here are developers and that's where your focus is, but, as an end user, manpages and READMEs and whatnot are just as bad IMHO. Some are overly technical, some have vague examples, some aren't technical enough, relevant information is scattered among different sources.

                  Like, as a Linux user, I've learned more about how to setup my AMD GPUs from random Google searches, Arch Wiki/Gentoo Handbook, and Phoronix threads than I have from AMD. AMD's Linux information straight up sucks due to how scattered about all of it is and how generic their official information is. There should at least be some pages on an xorg.conf showing my xorg.conf (it contains the current defaults) and what the containing values do, a second xorg.conf showing a multi-montior setup,and a multi-monitor, multi-gpu setup; an advanced setup page with AMD_DEBUG and other environment variables; another advanced page about overclocking.

                  If I wasn't a more technical user I know that I'd have one hell of a time trying to use my AMD cards and that having a 260x, requiring me to use the CIK stuff to use AMDGPU, assisted me by forcing me to have to do it all the technical way and to try things in multiple ways before calling something a bug since it was "experimental". If I were a non-technical user and just bought a 580 never using my 260x or any other previous AMD card, I'd think the 580 was crappy due to all the tearing and vsync issues inherent in Linux and not the card itself.

                  I'm not trying too be hard on AMD because it's both them and distributions. It's not like every distribution has good documentation on all of that for Intel or Nvidia and not all users will trust a random Phoronix post or are able to use the Arch Wiki to fix a Suse problem.
                  Last edited by skeevy420; 04-14-2019, 10:36 AM. Reason: bad grammar in a documentation post...just damn...

                  Comment


                  • #10
                    A large part of Docker's success has been the project's documentation (not just source code). I have not found any project that even rivals it in this regard: https://github.com/docker/docker.github.io They have kept it simple by using built in language documentation and markdown. Seems to be working well for them so far.

                    Libraries are another story though.

                    Comment

                    Working...
                    X