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

  • OlafLostViking
    replied
    I am just setting up a Prosody server and realized how improvable the documentation coming from the project itself is for newcomers (or at least me), when you want to set up a "good" XMPP service. Just a quite minimal introduction and a non-sorted list of modules (sometimes with only the module name as "documentation"). Some important ones are available only as community module. The Debian backports also contain only parts of the modules available. No real overview or step-by-step howtos. I'm collecting needed settings from blog entries and guessing. If anybody here knows about a good howto with explanations, it would be very nice if you could post it in here :-)

    Leave a comment:


  • coder
    replied
    Originally posted by debianxfce View Post
    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.
    I completely disagree with involving outside authors, in this scenario. An API must be documented by its original authors. Someone coming along, after the fact, cannot reliably distinguish implementation bugs from original intent. And once documented, a behavior becomes virtually set-in-stone, making it very difficult to change - even if the documented behavior is a bug and problematic.

    The kind of documentation it makes sense for them to write are things like intros, tutorials, conceptual overviews, translations, trouble-shooting guides, etc. Maybe they could flesh out the core API docs with some examples, as well as some spelling and grammatical fixes.

    The only way I'd have anyone else writing API docs would be if you could really get the original developer(s) to carefully proof-read the resulting docs. Even then, it's not ideal. The ideal way to document an API is before & during implementation. Afterwards, even the original authors might have trouble recalling their intent, in a few places.

    Leave a comment:


  • skeevy420
    replied
    Originally posted by debianxfce View Post
    I did a search of the word "linux" at the AMD Knowledge Base. I'll sum it up.

    17 results: 12 are various AMDGPU-Pro install guides, two are LunarG install guides, one is about enabling FreeSync, one about installing Catalyst headless for Cent OS, one about ROCm for a FirePro.

    "xorg & x.org" : both 0 results
    "mesa": 1 result and is one of the AMDGPU-Pro install guides above
    "kernel": 4 results, more of the same AMDGPU-Pro guides
    "environment variable": 7 results, 5 of the same guides and the 2 LunarG guides
    "AMD_DEBUG": 0 results
    "R600_DEBUG": 0 results

    Like I said before, Phoronix is a better source of information on AMD GPUs than AMD themselves. I love my AMD cards. I do not love how all the documentation is scattered everywhere and how not even AMD has links to it all.

    Leave a comment:


  • schmidtbag
    replied
    Originally posted by debianxfce View Post
    The Alsa documentation is good enough, I found my .asoundrc somewhere. With the loopback driver you can record desktop audio. Check your audio devices with the command aplay -l and set the default audio output device number
    Maybe it's good enough today; like I said, it's been a while since I looked at it, but a couple years ago the vast majority of it was useless. ALSA's documentation is good enough for relatively simple things, such as doing nothing but a loopback driver. But it becomes increasingly more cumbersome as you add more functionality or are handling multiple output channels.
    Meanwhile in PA, you don't have to configure anything - you can just run pavucontrol and use that to assign the audio input source (which can be any output source).
    Pulseaudio is typical IBM garbage software. IBM software reinvents the wheel with poor results.
    If you actually knew what it did then you'd know it isn't reinventing anything. PA isn't a replacement to ALSA, seeing as it depends on it.

    Leave a comment:


  • skeevy420
    replied
    Originally posted by debianxfce View Post

    You are comparing to macos, android or windows. Every user knows how hard is to solve technical problems in those systems. You can not do much. Windows users install the OS again or other hardware to solve problems. AMD open source documentation for end users do exists now:
    Amdgpu kernel doc: https://dri.freedesktop.org/docs/drm/gpu/amdgpu.html
    Xorg doc: man amdgpu: https://www.mankier.com/4/amdgpu

    There is even a distribution for AMD graphics. https://www.youtube.com/watch?v=fKJ-IatUfis
    And very little if any of that is hosted by AMD. Some regular end user would have to know what Mesa was, what modules were, either the proper terms to Google or the proper commands to enter in a terminal, and likely more to use any of that. People like you and I can use that information, someone like my Mom couldn't...at least not how any of it is written in their current forms. I say all of that as someone who painfully learned a lot of stuff sifting through man pages -- it shouldn't be that hard and difficult to find the right information and the next generation of users shouldn't have to suffer like we all did.

    Like I said, I wasn't trying to rag hard on AMD since it's a problem that effects all Linux users for a lot of hardware and software as well as it wouldn't be on AMD to provide some of that information since Ubuntu, Suse, Manjaro, Debian, and Fedora might do certain things differently from one to another...but a noob-level general overview and links to relevant distribution documentation would be nice.

    On projects like AMDGPU that consist of multiple components, it just kind of sucks having to go to each component and read their write up that may or may not have the information one needs. Ever try looking up AMD_DEBUG stuff? I come across Phoronix threads more than I do actual documentation. I learned about R600_TEX_ANSIO here. The EQAA env variable documentation is sorely lacking...I had to read the damn source code to figure it out...and, yes, you're more likely to come across a Phoronix post or article when looking up EQAA too. IMHO, Phoronix is 50% of AMDs documentation on AMDGPU . Thanks for sifting through mailing lists and commit histories Michael .

    Ideally, AMD, no, "Random Company or Project" would have great write-ups that covered both end users and developers and then the various distribution guides could adapt the RCoP documentation to fit how they do things.

    Leave a comment:


  • Bsdisbetter
    replied
    Originally posted by milkylainen View Post
    That's actually a brilliant idea. Sorely needed. Some projects are severely lacking.
    Some? Most.

    Leave a comment:


  • kravemir
    replied
    Originally posted by skeevy420 View Post

    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.
    Software is as good as it's useful. For end users, different kind of documentation is needed. What you're saying is (also) bad structuring of documentation. README should target software users, and if software is application, then it should target end users, and provide relevant information for end users,..

    Also, quality aspects are needed, like works out of the box, stability, performance,...


    Leave a comment:


  • OMTDesign
    replied
    Goo to see that this is initiate is being offered internationally, just like their Summer of Code. I wonder what projects Google is eyeing, other than Qt, for manual pages?

    Leave a comment:


  • NotMine999
    replied
    Great idea ... in theory.

    Sadly Google has a bad track record of dropping projects. I hear that there is even a web site that documents that fact, but I have not bothered to look it up.

    Most FOSS developers that I have encountered over the years either: (1) don't get paid to write "proper documentation"; or, (2) do not have time between R/L and coding to write the necessary documentation of their code; or, (3) seem to have no desire to write documentation, preferring to fallback on bug report tools like Github and Sourceforge to document their code.

    Leave a comment:

Working...
X