Help Source

Viewing 2 reply threads
  • Author
    • #108269
      Topics: 18
      Replies: 4872
      Points: 1,903
      Helping HandTeam Member
      Rank: Community Hero

      Comment-based help has long been considered a best practice. However, it doesn’t natively support localization or online help updates. Markdown has emerged as a better source in some ways. Using PlatyPS, it can be turned into “real” MAML-based help, which supports localization and online updates, and obviously offers an easy transition to online web-based help, too.

      I recently saw a Twitter conversation, however, about using comment-based help in order to keep the docs “attached” to their code. Then, in a CI pipeline, comment-based help is extracted, turned into Markdown, and then published to the web or to MAML files.


    • #108280
      Topics: 2
      Replies: 1013
      Points: 2,093
      Helping Hand
      Rank: Community Hero

      As per the SchoolHouserRock days (yep, I know, dating myself here ‘8^}’).

      RIF (reading is fundamental) – but many in tech often choose not to, even the help files. They just jump right in and wing it, with all the assumptions at hand.

      The old — ‘pffft! I don’t need no freaking manual. mindset, or the new default —  TL;DR mentality.

      So, I’d prefer the latter and the primary reason the above. Yes, it does bloat the total lines, but at minimum, if one chooses not to take the effort to read the .md, books, view free videos to take a paid course, they’ll always have these crib-like note resources to browse, in-line.

      The extraction for expanded help would take care of those voracious readers.

    • #108301
      Topics: 1
      Replies: 10
      Points: 51
      Rank: Member

      I now teach and recommend comment based help for stand-alone functions. But for modules, Platyps is the way to go. And you don’t even need to know much about markdown since it is basically fill in the blank. All you really need to understand is a code fence for the examples.

Viewing 2 reply threads
  • The topic ‘Help Source’ is closed to new replies.