Documentation of deprecated features

This Discourse and the previous Google Group contain an enormous amount of information about Stan beyond what is found in the official documentation. At the same time, previous solutions/posts may rely on deprecated features and newer syntax/solutions may be available. One problem that arises from this is that the link between current features and deprecated features that underlie a fair amount of the knowledge base on here may be difficult to identify.

One factor I’ve found contributes to this is how deprecated features are documented. Deprecation moves features in the reference manual to the Deprecated Features section 13 Deprecated Features | Stan Reference Manual. While older versions of documentation can be consulted and this successfully helps others find current features while preserving these features in the documentation, it can make translating solutions from older posts more difficult and cause confusion among newer users. This is because when users go to Section X of the documentation and don’t find anything corresponding to the syntax underlying the solutions ,they aren’t sure if the feature is not well-documented, they are looking in the wrong place, the feature is deprecated, etc. Of course, they might have memorized the Deprecated Features section or may deep dive into older documentation (if they know where to look), but this seems unlikely.

Sometime the documentation seems to acknowledge this, other times not-so-much. For example, 7.2 Assignment statements | Stan Reference Manual contains a footer:

In versions of Stan before 2.18.0, the operator <- was used for assignment rather than using the equal sign =. The old operator <- is now deprecated and will print a warning. In the future, it will be removed [LINK HERE].

This is nice insofar as it alerts people when they’re visiting assignment that this change happened/will happen. Of course, this would need to be updated once it is removed and is thus problematic in some way. In contrast, array syntax documentation doesn’t seem to mention construction with brackets array syntax doesn’t work although creating real arrays with real n[5] is deprecated but found in many old examples.

I’m wondering then if simply adding a section at the bottom of pages with links to the corresponding deprecated feature pages any time a feature is removed would impose little burden but also help people not quite ready to slay all dragons with Stan.

3 Likes

This is definitely a problem not just for us, but for projects like Python and Julia, which have tons of deprecated behavior. Do you have any idea what those projects do in this situation?

That’s actually a bug. We didn’t mean to leave any discussion of deprecation in the main text!

We could change our doc policy and add links like that at the bottom of sections in the language reference. I’d be OK with this even if it introduced some redundancy.

The best thing to do is to open an issue in our docs repo where we can discuss this. If our other devs are OK with tis plan and you’re willing to make the changes, we accept pull requests.

1 Like