78

I'd like to propose a method of flagging obsolete methods and practices within Documentation.

Similar to how version-specific code is placed in a wrapper:

<!-- if version [eq 1.0] -->
Content only relevant to version 1.0.
<!-- end version if -->

Resulting in this:

Screenshot of version wrapper

I'd like to propose something like this:

<!-- deprecated [gte 2.0] -->
Content deprecated in versions 2.0 and greater
<!-- end deprecated -->

That would result in something like this:

enter image description here

16
  • 22
    -1, Documentation is already FUBAR, so there's little point in making incremental improvements (partially tongue-in-cheek) (paraphrased from source)
    – user4639281
    Commented Jan 18, 2017 at 20:50
  • 24
    I hope you're joking, if not that's a poor attitude. Review queues are ancient, saddled with problems that originated years ago. Documentation is a new product and if there are problems with it, now is the time to start fixing them. Just because you don't like something doesn't mean it isn't useful to others in the community.
    – miken32
    Commented Jan 18, 2017 at 22:09
  • 46
    Honestly, Documentation is so far gone, I don't see how any improvements can be made without drastically changing the platform, removing all of the content, and starting over. I have tried to give Documentation the benefit of the doubt multiple times, but there is just too many fundamental issues. The review queues actually work, and have served a purpose up to this point. Documentation doesn't work, has never worked, and does not serve any identifiable purpose.
    – user4639281
    Commented Jan 18, 2017 at 22:31
  • 22
    Although I agree with both of you above, Documentation isn't going anywhere any time soon so discussion about its usefulness isn't really helpful. If it is to actually get anywhere close to its pipe dream then it is feature requests such as this that is going to get it there.
    – Sayse
    Commented Jan 19, 2017 at 10:42
  • 11
    I'm with @Sayse on this. If you're so anti-documentation, please leave the vitriol to posts where it's more relevant.
    – DavidG
    Commented Jan 19, 2017 at 10:58
  • 21
    I support this proposal, as I would love to use it to mark the whole documentation feature as deprecated. </vitriol> Commented Jan 19, 2017 at 11:17
  • 2
    Isn't it against the SO rules to downvote something just because you don't like it? IIRC, Downvotes are only to be used on the basis of actual problems with the content, otherwise I could just decide that I don't like PHP so I'll downvote every PHP question.
    – SGR
    Commented Jan 19, 2017 at 11:59
  • 9
    @SGR It's a bit different here on meta - it's perfectly valid to downvote feature requests if you don't think it's a good idea etc - helps show community support for such an idea, and may help prioritise things with the dev team. Commented Jan 19, 2017 at 12:01
  • 3
    @SGR not on meta, on meta the votes are an indication of your agreement with an answer / proposal / question.
    – luk2302
    Commented Jan 19, 2017 at 12:01
  • There was a feature-request concerning added versus implemented on the unsearchable QA beta doc website that is related to this.
    – Knu
    Commented Jan 20, 2017 at 3:35
  • 4
    @SGR There are no rules whatsoever about how you spend your votes. As long as you're not abusing the system to vote, you can vote however you please.
    – Rob Mod
    Commented Jan 20, 2017 at 3:58
  • 1
    @DavidG I don't see how what I have said here qualifies as "cruel and bitter criticism." I was merely voicing my opinion, in a total of two comments nonetheless. The first comment is an entirely tongue-in-cheek reference to a similar comment on one of my feature requests that I felt adequately expressed my opinion on the feature request here. My second comment was a completely honest response to the rebuttal of my first comment. I don't see why I shouldn't be allowed to express my opinion on feature requests solely because I don't like the feature. Just a note, I haven't actually voted on this
    – user4639281
    Commented Jan 20, 2017 at 23:48
  • Nice request. One maybe could generalize it to allow for custom tagging (like the Q&A site has). Commented Jan 21, 2017 at 9:22
  • 3
    @TinyGiant Maybe no "cruel and bitter criticism" but commenting on a specific feature request with a general reply is at least in my opinion complaining at the wrong place. See for example Is Documentation failing?. Commented Jan 21, 2017 at 9:26
  • @Trilarion curious what you're referring to?
    – miken32
    Commented Jan 23, 2017 at 16:49

1 Answer 1

4

I like this idea and brought it up with the Docs team last week. As a first pass, we already have the ability to show something is depreciated:

<!-- if version [lt 2.0] -->
Content only valid in versions before 2.0.
<!-- end version if -->

Valid before 2.0

Semantically, that isn't quite the same thing since languages often discourage the use of features before yanking them away altogether. (It also lacks the punch of the red outline.) But since we aren't attempting to be the official Documentation I think it's ok to ignore that distinction. Think of it as less prescriptive and more descriptive. If a particular way of writing code is being replaced, it probably makes the most sense to show the new way first and then the outdated way with a little text warning:

More nuanced version.

That way, the example can provide a good deal of nuance between various approaches language designers take to depreciation:

  • Tell people not to use the feature, but never really get around to removing it.
  • Discourage use of a feature for a few versions with warnings then take it away.
  • Remove the feature with minimal advanced notice.
  • Maintain two separate branches.

A single depreciated syntax can't communicate all the variations without becoming less convenient than just using words.


That said, I can imagine some extra styling being added to older versions. Perhaps not vivid red as in the question, but maybe a lighter border. Or perhaps hiding the code block somehow. That would avoid adding syntax to inline versions while still getting the point across that using this bit of code might not be for everyone.

In any case, I'm declining the idea not because I think it flawed, but because it requires a little more thought to get right.

2
  • 1
    wouldn't status-review be more appropriate since you aren't really declining it but it is more along the lines of "let's look at this in more depth to see if we make it right?" Commented Feb 6, 2017 at 18:36
  • @psubsee2003: I don't like to use the review status for things that we aren't actively working on. (I probably should have used it last week to show we were thinking about it.) Since there's no plan to do the next step, I'm declining it. There's always been a "for now" quality to declining around here.
    – Jon Ericson StaffMod
    Commented Feb 6, 2017 at 18:43

Not the answer you're looking for? Browse other questions tagged .