No announcement yet.

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

  • Filter
  • Time
  • Show
Clear All
new posts

  • #21
    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 &" : 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.


    • #22
      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.


      • #23
        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 :-)