Author Posts

August 11, 2018 at 3:18 pm

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?

August 11, 2018 at 7:53 pm

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.

August 12, 2018 at 3:47 pm

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.