Help Source

This topic contains 2 replies, has 3 voices, and was last updated by

 
Participant
1 year, 1 month ago.

  • Author
    Posts
  • #108269

    Keymaster
    Topics: 13
    Replies: 4872
    Points: 1,843
    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.

    Thoughts?

  • #108280

    Participant
    Topics: 2
    Replies: 999
    Points: 1,946
    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

    Participant
    Topics: 1
    Replies: 10
    Points: 22
    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.

The topic ‘Help Source’ is closed to new replies.