# Engineer and document a technote deprecation process

XMLWordPrintable

## Details

• Type: Story
• Status: In Progress
• Resolution: Unresolved
• Fix Version/s: None
• Component/s:
• Labels:
• Story Points:
0.2
• Team:
SQuaRE

## Description

Design a technote deprecation process, engineer it, and document it.

The process was sketched for DMTN-026:

 deprecation: date: 2017-03-16 message: >- A sentence or two explaining the deprecation. replacements: - {"name": "DM Developer Guide: Python wrappers for C++ with pybind11", "url": "https://developer.lsst.io/coding/python_wrappers_for_cpp_with_pybind11.html"}

2. At the top of your index.rst, but below the :tocdepth: 1, including a warning directive:

 .. warning:: A sentence or two explaining the deprecation. Date deprecated: 2017-03-16. Replacement links: - DM Developer Guide: Python wrappers for C++ with pybind11 _

Engineering notes:

• Make it so that only (1) or (2) are needed to officially deprecate a technote.
• Add a canonical-url header into deprecated technotes pointing to a replacement link so that Google will prefer the replacement URL over offering a deprecated document.

## Activity

Hide
Tim Jenness added a comment -

Just a note that DMTN-024 (DM-9466) needs to have it's deprecation record updated to match this standard.

Show
Tim Jenness added a comment - Just a note that DMTN-024 ( DM-9466 ) needs to have it's deprecation record updated to match this standard.
Hide
Jonathan Sick added a comment -
Show
Jonathan Sick added a comment - Also deprecate https://github.com/lsst-dm/dmtn-054  ( Krzysztof Findeisen )
Hide
Tim Jenness added a comment -

I feel strongly that deprecated documents should still include the original content along with a big deprecation notice. DMTN-054 currently just says "this is deprecated". I don't think we should always rely on the full git history being around. I could change my mind if we are permanently archiving the previous version with a DOI and the deprecated version knows about it. The deprecation notice should also include a reason along with a pointer, if relevant, to a replacement document.

I think this implies that there needs to be a "deprecated" class option for latex files so that a big deprecation banner can be included similarly as we use for "draft".

Show
Tim Jenness added a comment - I feel strongly that deprecated documents should still include the original content along with a big deprecation notice. DMTN-054 currently just says "this is deprecated". I don't think we should always rely on the full git history being around. I could change my mind if we are permanently archiving the previous version with a DOI and the deprecated version knows about it. The deprecation notice should also include a reason along with a pointer, if relevant, to a replacement document. I think this implies that there needs to be a "deprecated" class option for latex files so that a big deprecation banner can be included similarly as we use for "draft".
Hide
Jonathan Sick added a comment - - edited

I feel strongly that deprecated documents should still include the original content along with a big deprecation notice.

I do fully agree with that. In that case an author scrubbed both the content and the title. I put the title back so it wouldn't raise red flags for me on the www.lsst.io page (I was looking through it over the weekend and through the build had broken). I just haven't put the content back (yet). But I like your idea (keeping the content or archiving with a DOI.

I think we can incorporate all those features into a deprecation process.

Show
Jonathan Sick added a comment - - edited I feel strongly that deprecated documents should still include the original content along with a big deprecation notice. I do fully agree with that. In that case an author scrubbed both the content and the title. I put the title back so it wouldn't raise red flags for me on the www.lsst.io  page (I was looking through it over the weekend and through the build had broken). I just haven't put the content back (yet). But I like your idea (keeping the content or archiving with a DOI. I think we can incorporate all those features into a deprecation process.
Hide
Krzysztof Findeisen added a comment - - edited

In this case, the author scrubbed the content to avoid it getting published on https://www.lsst.io/ (particularly since it had never been "published" out of draft status). If the site doesn't publish docs that are marked as deprecated in their metadata, then I have no objections to keeping the text.

I would object to unfinished documents getting officially DOIed.

Show
Krzysztof Findeisen added a comment - - edited In this case, the author scrubbed the content to avoid it getting published on https://www.lsst.io/ (particularly since it had never been "published" out of draft status). If the site doesn't publish docs that are marked as deprecated in their metadata, then I have no objections to keeping the text. I would object to unfinished documents getting officially DOIed.

## People

• Assignee:
Jonathan Sick
Reporter:
Jonathan Sick
Watchers:
Jonathan Sick, Krzysztof Findeisen, Tim Jenness
0 Vote for this issue
Watchers:
3 Start watching this issue

## Dates

• Created:
Updated: