A suggestion for automatic categories for wiki pages...

Mark Aitchison <M.Aitchison@xxxxxxxxxxxxxxxxxx> · Tue, 1 Aug 2017 16:11:33 +1200



    Taking a random page like https://fedoraproject.org/wiki/Administration_Guide_Draft/NFS
      I notice there are several obvious (and some not-so-obvious)
      indications that the page is out of date.  I think it would be a
      good idea, and probably can be done automatically for the most
      part, to have a clear indication of the state (score?) of each
      wiki page to indicate how valid and up to date it probably is. 
      That indication should be a clear box at the top, and (if the page
      is so out of date that it may be unusable) it could change the
      background to (say) some shade of pink.
    These are the things that could be checked automatically:
    
      uses a command or suggests installing a package that doesn't
        exist in the latest release (other than in a section clearly
        headed for "Older Versions")
      uses a command (like yum) that is deprecated/out-dated (that
        might include any system-config-xyz options since they seem to
        be disappearing?)

      
      does not have a section on testing the changes that have been
        made (if the advice had included "edit" or "install" anywhere).
      the latest release of Fedora mentioned anywhere on the page is
        over 2 years old.
    
    There should also be a clear feedback method on each page (like
      "This answered my question"/"This didn't tell me everything I
      needed to know"/"This did not work for my system"/"I think it
      could be done or said more simply"/"The page misses some important
      (e.g. security) issue" plus an option to be contacted for more
      details. That should also (after human checking) make it's way
      into the page's "usefulness score".  And there should be a ranked
      list of pages needing "some love" with an indication of just how
      in need of attention they are, so pages don't remain out of date
      too long.

    
    Related to that, and something that could (like Wikipedia, etc)
      be automatically checked and made obvious to editors), there
      should be some sections on most pages in a standard format, e.g.:
    
      a subsection "Documentation checked up to release nnn"
      a subsection "Older versions" describing differences for users
        of earlier releases.

      
      instructions on what firewall changes are needed (if none say
        so for any page mentioning installing anything or changing any
        system option/file)
      a "For example" section
      a "Checking your changes" section
      a "Security implications" section
      a "Why you might not want to do this" section(!!), for example
        saying there are other ways to do the same thing, or how much
        performance hit you might get, or how things may freeze for a
        while if another system is down, or security worries, etc.  And
        it shouldn't just list options (e.g. no_subtree_check) it should
        either say why to choose/disable the important ones, and perhaps
        link to some page with a discussion - perhaps forum-linked.

      
    and ways to link to the pages that we can be pretty sure will
      stay valid for a long time... e.g. if the page has a quick
      explanation of how to allow SELinux or a firewall to allow the
      changes to work, but you want to link to more detailed
      instructions on another page, then that link should stay valid for
      a long time. Maybe a way, even, for editors to say "this page
      depends on this link", although it should be possible to work this
      out automatically and warn any person editing editing the linked
      page if it will break links from other pages. 

    
    Thoughts?

      Mark Aitchison

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