Proposal 20: Introduce a {{deprecated}} Macro for Marking Deprecated Content Inside Active Pages
Hello, everyone!
There are cases when the documentation contains deprecated content embedded in pages that are not themselves deprecated.
For example, a feature might be partially deprecated, or only a specific parameter, UI element, or behavior is outdated, while the rest of the page remains relevant. The {{version}} can’t be used macro for this, because it already has specific rules and is not meant for marking deprecated text.
A {{deprecated}} macro could solve the problem. The behavior could be:
Wraps a block of text.
Automatically adds styling (highlighted tag) indicating that the content is deprecated.
Could support an optional parameter such as: since= (e.g. {{deprecated since="10.2"}}...{{/deprecated}}).
Yes, while the version macro is supposed to be used temporarily and then removed from the doc, deprecated content can stay for a long time (as long as it’s part of what we distribute we need to continue documenting it).
the version macro for changes with a before property for parts of the documentation that can be safely removed once the impacted versions are not maintained anymore
the deprecated macro for parts of the documentation that are expected to stay even once the impacted versions are not maintained
Did I get this right?
+1 as the notion of deprecated content seems useful.
PS: I could use a mock to better understand what deprecated content would look like.
Note that in this example the full content is deprecated but we could still wrap the macro around the full content. We also indicated that it’s deprecated in the title in this case.
yes, “before” or “since”, depending on the use case. For something existing use “before”, for something new use “since”. cc @elenicojocariu to update the doc guide if need be.
Almost. If something is not maintained then it’s moved outside of the product and thus the doc should be removed from the XS doc when it falls out of the 1 year period. You could have both “version” macro used around a “deprecated” macro. At some point the version macro will be removed from the doc but the deprecated one will stay as long as we still support it (ie we still bundle it).
As long as the code is still bundled in XS, it’s supported (even if deprecated).
+1 for a deprecated macro from me.
I agree with adding a version. Is there any reason why this should be optional? I don’t see a case where we have something deprecated without a version for its deprecation (even if it’s just approximative, in which case it still gives an idea of how old it was deprecated for). I believe in our use case a mandatory since would make sense.
We could enforce that the deprecation is done properly with more parameters. E.g.
Useinstead a link or text referencing what this was replaced with. AFAIK we don’t want feature regression in XWiki and every deprecation comes with a new tool that produces the same result but with an improved implementation or UX.
Thank you for the clarification! Do we have a place where this is written down in our doc guide? I remember scouring through plenty of our doc pages to try and find information similar to this. I remember a somewhat recent example of the definition being unclear causing small misunderstandings Proposal: deprecate silk icons theme
Note: This could be a great entry for the glossary. Deprecated has a special meaning in the XWiki project that goes beyond the english definition.
Thank you for sharing your progress on the documentation reorganization!
Lucas C.
Yeah wasn’t sure since it’s not like an api where it’s easy to point to another api. Here it maye some text which could be elaborate (several lines) and we could use the content of the macro to describe what should be used instead.
I’m not against it though and it would be a good way to ensure it’s always mentioned if we make it mandatory. We would need to decide how it’s displayed though.
Re the parameter name, we could also use some other words like replacement (or “substitute”). Or use useInstead as you proposed.
For me this is not related to the doc but the code. Everything that is bundled is supported (by definition since we don’t bundle broken stuff). And thus needs to be documented, like any feature. Not sure what you have in mind re the doc guide.
We could provide a definition of “deprecated” in our dev practices if you want. Basically what it means for me:
The code is still supported (since it’s still bundled), i.e. it’ll continue to work.
The dev team will not spend time to improve it (but we’ll fix bugs if they arise so that it’s not broken).
Developers are advised to stop using the deprecated apis since we’ll move them ASAP to legacy modules, and to make that easy we need to usages of the deprecated apis.
Users are advised to move away (use the replacement) since in some relatively close future, the code can be removed (moved as a non-bundled extension for example).
You’re referring to a developer glossary or some special doc glossary? (we haven’t talked about this in any proposal so far). Because for users, right now the idea of the glossary is to explain terminology that the user sees inside XS when they use it.
I was thinking of a developer-level glossary entry (XWiki.org Documentation Reorganization (batch 5)). When developer-level users develop for XWiki, they will at some point come in contact with this word (by reading through some doc or through the sources) and it could make things easier for new ones if we provide a clear definition.
But the goal of the deprecated macro is not only for developer APIs. It’s also when deprecating features and other stuff. So it seems to me it’s more something related to understanding the documentation.
With delay mentioning that +1 for deprecated macro. But there’s still…
Difficulties that will arise and no one didn’t think about it. This is why you should consider using the XWiki warning box macro. Why? The challenge that editor will meet in not being able to find specific version where parameter was deprecated due to reasons: 1) was replaced (by adding new ones); 2) was removed (because the API was reworked). In such situations, neither the history of Jira nor the commits in the repository or the history of file changes will contain information or differences where something was marked as @deprecated or even removed.
Because of this, I have a question, shouldn’t the content of the documentation pages have been changed where the values/parameters are no longer available in XWiki or somehow to define what to do with in such case here?
This reminds me of the changes I made on one of the pages this year (around middle of summer or end of summer) and now reading this discussion I see the need to return the deleted one, why I deleted it is a separate case because I spent a significant part of the time reading and searching for changes in the code itself. I need to find my notes regarding this and will mention it in Matrix chat.
Not a real issue since the main use case for the deprecate macro is when writing doc for a new features/api added that replaces another one, or when a vote/proposal is agreed to deprecate something, etc. So we always know the version of XWiki at that time.
Ofc if you try to use the deprecated macro for something that was deprecated 10 years ago, you’ll need to do some archeology, but 1) you can if you want (including asking on the #xwiki chat) and 2) If we really don’t know, we can always use something like since="Before XWiki 10" (not recommended but as a last resort).
and yes, I will share the example with the room, just need to find my notes regarding it with the tickets that only partially mention the old parameter.
The information to describe the deprecation is used to set the content and title in an error box at the top.
The deprecated content is indented with a border continuing the highlight from the error box on the left side, all the way down.
In edition/preview modes, the warning box is not visible. This way, it’s way less distracting, but it’s still easy to separate doc for deprecated features from the rest.
Side thought: a similar pattern could also work to display renderingerrors as an improvement for XS
