2

I find myself never writing documentation. This isn't because the tools don't exist, but rather because writing full-fledged Mathematica documentation is tedious with linking, example writing, overview page creation, etc.

I'm trying to come up with a more light-weight documentation structure that would cover 90% of use cases and that can be programmatically generated, assuming I have usage messages and can pull argument patterns out of DownValues, UpValues, and SubValues. I can currently replicate that built-in docs and push it to the web, but the problem is writing them is just too much of a hassle and I never do.

Does anyone have suggestions as to what they would like to see in a documentation format?

Here's an example:

Single Notebook Package Overview

I think for 60% of my use cases I really only need one Notebook with a bunch of usage blocks like:

myFunc[arg1, arg2] does a thing
  arg1: Integer
  arg2: Integer
myFunc2[args...] does another thing
  args: Integer sequence

And then these can link to more detailed pages on myFunc and myFunc2 that I can write up only for some small subset of my functions.

4
  • 3
    1) messages it can issue 1b) ways it fails Failure/$Failed/unevaluated w/o message? 2) attributes 3) possible values for options – Kuba♦ May 27 '19 at 19:31
  • @Kuba 1b is probably the only hard one there. The rest I can mine programmatically I think... – b3m2a1 May 27 '19 at 21:37
  • @Kuba and any other moderator. This doesn't look like a meta question to me. I suggest it be migrated to the main Mathematica.SE site. – m_goldberg May 30 '19 at 0:32
  • 1
    @m_goldberg it felt too opinion based for main to me, though. I was more-or-less going off the precedent set by this question. – b3m2a1 May 30 '19 at 6:01

You must log in to answer this question.

Browse other questions tagged .