It is useful to try and capture the story of a predicate or a feature in the docs?

The title ends in a question mark so I guess I feel the answer is “NO”; however, I would like to know how others see this. This post is provoked by the suggestion of @abaljeu in that thread there.

My own experience with “versioned docs” is a mixed bag. Just the other day I was fighting my way through the docs of Python’s ipaddress and there are some real gems there, for example:

https://docs.python.org/3/library/ipaddress.html#address-objects

I don’t know if those are auto-generated or hand-written but we have incompatible behavior going back and forth between versions :smiley: [EDIT not sure really, let’s just say it is quite confusing]

I would rather circumvent the issue altogether and stick with the “latest” or if I can’t find motivation to upgrade/test/refactor then just never touch the code again until it is time to throw it away.

(I missed a lot of words here; what I meant was, I write my code for the latest shiniest software at the time. Then, I have two obvious options: either update regularly and aggressively refactor every time upstream has breaking changes; or decide to freeze until it is time to throw my code away and only fix bugs in my own code. What ends up happening in practice is that most of people most of the time are forced by the circumstances to take some middle road. For example, you don’t want to change any features in your own software, but a vulnerability fix upstream forces you to upgrade your dependencies and in order to do this you must refactor. Maybe that’s just how it is and in that case studying the changelogs is inevitable…)

Another consideration is that that kind of documentation is invaluable for closed-source software but the combination of open souce and git supersedes the need for it to some degree.

On the other hand there is a rather big precedent with the “SWI-Prolog extensions” section but I would argue that this is on a different level conceptually.

What are your experiences and opinions?

2 Likes

SWIMM is a startup venture dedicated to continuous documentation by integration of documentation with git and git based code versioning.

Apparently, SWIMM sees a lot of traction in organizations who see a lot of value for documentation to onboarding – given the average churn of 2 years in hitech.

Its apparently also free for open source projects …

It is of course good they call it SWI MM :slight_smile: It is totally unclear what they do though. Their claim for it to work about of the box anywhere is rather unlikely considering SWI-Prolog’s documentation comes from various sources. If anyone wants to try it, please report.

Overall, we have seen some hints on how to find things. One option might be to integrate these more closely into the website. For example a button that tries to extract relevant commit messages and/or the source. One of the problems is that changes indirectly propagate to closely related predicates where functionality is shared. So, you’d need a dependency tree. That is doable of course. That could also be used to browse the relevant source quickly online. I don’t know the feasibility of this. It is also hard to guess how many people this would make happy.

Python’s documentation takes some skill to read. There’s the reference documentation, often one or more PEPs (enhancement proposal), and long discussions in the python-ideas mailing list. Plus various tutorials, which are often wrong in subtle ways (which doesn’t stop them from being popular). It’s a somewhat flawed system, but at least the PEPs help in understanding the rationale and intended use of a feature (the PEPs also summarize the mailing list discussions).

Yeah sure but ain’t nobody’s got time for that :smiley:

Here is what I was referring to (how to confuse a cat):

Changed in version 3.8: Leading zeros are tolerated, even in ambiguous cases that look like octal notation.

Changed in version 3.10: Leading zeros are no longer tolerated and are treated as an error. IPv4 address strings are now parsed as strict as glibc inet_pton().

Changed in version 3.9.5: The above change was also included in Python 3.9 starting with version 3.9.5.

Changed in version 3.8.12: The above change was also included in Python 3.8 starting with version 3.8.12.

I really didn’t mean to shit on Python in particular, I just used this as a practical example of the perils of (automated?) annotation of the historical developments.

Agreed. But nobody seems to have come up with a better way of doing things. :wink:
Even with full-time tech writers. (When I was at Google, there were running jokes about the documentation being always out of date … and that was with a team of tech writers who did a very good job of organizing things and keeping things up to date. IBM did an excellent job of keeping its external documentation up-to-date, but the cost was significant.)

I haven’t tried SWIMM, but did attend a webinar, which looked very promising.

I work with a similar tool which has a graphical user interface that I find more appealing to me – but, my tool currently lacks significantly in that it doesn’t synchronize with code changes – to show me where documentation I wrote may have become outdated.

SWIMM has this feature built-in and its one of their killer features to help overcome documentation staleness.

They promote a continuous documentation process and I think recently they integrated into JIRA as well.

p.s. as an aside - as a startup they were well funded some time ago with 27M USD.

Burning through venture capital?

I guess that requires the tool to at least know where the documentation for a particular piece of code is. For SWI-Prolog it resides in a .pl file, a .md file or a LaTeX file. For the Prolog code the PlDoc comment at least documents the code (typically) below it. The docs for foreign predicates in packages is also documented in the .pl file, but the code is in some C(++) file. How is any tool going to make this link? Then, changes may well be further down the combined Prolog and C(++) call tree. How is a general tool going to find these dependencies? [ I came across cflow yesterday, which promises to create a call tree for C code, but apparently it does so using rather superficial analysis as it gets it completely wrong when applied to the SWI-Prolog source ].

Even if you could fix these problems using a tool where you can add plugins/rules that explain how the source is organized, you get the real hard problem that changes to some predicate/function in the call tree do affect their callers. It is typically rather unclear whether documentation needs an update and if so, which.

My gut feeling is this can only work if the project organization and comment/docs organization follows pretty rigid rules. For a new project that is quite likely worth a try. For an old project the effort to get there is way too high. Of course, if SWIMM can do all this magic, I’m glad to use it :slight_smile: For now I do not believe in fairy tales :slight_smile:

2 Likes