29

There are some "classic" questions on Stack Overflow which were tremendously popular in their day, but which are now closed because they are not a single question with a canonical answer. As an example, Hidden Features of Python: an overly broad question with 191 answers as I write this, each different from the last.

There are some Internet articles which cover similar topics. They are highly useful, but by modern standards inappropriate for StackOverflow, except maybe as a series of canonical self-answered questions to provide common dupe targets. An example of this might be Common Python Gotchas.

Provided the appropriate format is followed and information isn't lifted from external sources without attribution, are these sorts of things on-topic and appropriate as Documentation Topics and Examples?

5
  • 6
    Common gotchas would be useful, especially for JavaScript ;) . Hidden features would be interesting, but their usefulness aside from code golf is debatable, and repwhores might have a nice time.
    – gcampbell
    Aug 2, 2016 at 14:41
  • 1
    @gcampbell I picked "hidden features" b/c I remembered that question specifically as an old-style question that reminds me of something that seems more appropo for Docs. I don't know if that's useful in other languages, but for Python it can be neat since it has some weird but useful features that don't appear much in related languages, like else clauses on try and looping constructs. Aug 2, 2016 at 15:16
  • 1
    I actually like reading about hidden features, but it's tricky to decide what counts and what doesn't.
    – gcampbell
    Aug 2, 2016 at 15:19
  • 5
    Perl is TMTOWTDI -- "There's More Than One Way To Do It". It's good to document all the ways to do something so you can read someone else's code!
    – Rick James
    Aug 2, 2016 at 21:13
  • 1
    Tips & Tricks are example centric, so I guess yes. Aug 3, 2016 at 6:32

1 Answer 1

30

I suspect an awful lot of Docs will end up being "tips and tricks". Without needing a question, this sort of thing accumulates.

And that's probably ok!

But... Please try to categorize them. Rather than throwing them all into a massive, impossible to navigate "Tips" topic, if you write such an example try to find or create a topic where it can live comfortably.

This should be fairly natural. You'll note that the top "hidden feature" of Python in that old question (chaining comparison operators) now lives comfortably under the Comparisons topic in Docs. You can find some of the others scattered around as well (often in topics that should probably be broken up a bit - a "loops" topic is crazy big).

In short, tips and tricks are great when they're practical - and even better when you can find them. So pick a relevant topic, write a title that reflects some useful activity, and go to town.

9
  • 4
    "Rather than throwing them all into a massive, impossible to navigate "Tips" topic" I think this is why most people feel aversion to have tips and tricks at all on documentation. If I need to sort something in Perl, I shouldn't navigate outside the "Sorting" topic and find the "Schwartzian transform" in there, not buried (or featured) in a "Tips & Tricks" list of stuff.
    – Braiam
    Aug 2, 2016 at 22:55
  • 2
    ' Rather than throwing them all into a massive, impossible to navigate "Tips" topic, ' Unfortunately every topic seems massive and impossible to navigate to me at this moment. I hope time and new features will change this. Aug 3, 2016 at 1:01
  • I just use search, @Two-BitAlchemist. Works surprisingly well. Content indexing has come a long way since 2008's SQLServer Full Text.
    – Shog9
    Aug 3, 2016 at 1:06
  • What if you're not looking for anything in particular? Say I'm new to Ruby. What do I search for? Aug 3, 2016 at 1:25
  • 2
    I'd probably search for "ruby", @Two-BitAlchemist.
    – Shog9
    Aug 3, 2016 at 1:28
  • 2
    I meant within the tag. Navigating the topics in whatever order they're presented is not very natural or conducive to learning. Aug 3, 2016 at 1:30
  • 2
    Well, that's the intent of the "overview" topic pinned to the top-right of the dashboard, @Two-BitAlchemist. Wouldn't say it's particularly useful for ruby just yet.
    – Shog9
    Aug 3, 2016 at 1:35
  • 2
    Oh wow... site blindness (right side in ad space) + light gray text on light gray background. I didn't even see that until you pointed it out. Aug 3, 2016 at 1:41
  • "I just use search, ...Works surprisingly well." If you know what you are looking for, yes. Some sort of index to give an overview of possible topics is still a good idea, I think. Aug 4, 2016 at 7:32

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