56

Yesterday I spent several hours creating a Topic with 6 Examples showing how to drag shapes on html5 canvas.

Today my Topic was deleted without explanation by moderator animuson.

The now deleted Topic.

While I'm not saying my Topic + Examples are masterpieces, I feel they would help someone incrementally learn about the steps required to make shapes draggable on html5 canvas.

I am frustrated because I don't feel my Topic is worthy of being deleted and that a single reviewer can delete my several hours of work.

Update

So from the comments I think I understand that Examples should be less narrative, less working demo, more pithy & minimal code chunks.

I'm still confused about the scope of Documentation Topics & Examples.

If the minimal example for a complex task is several hundred lines long, is that minimal example too long to be a good Example?

19
  • 4
    Here's the deletion event, for reference: stackoverflow.com/documentation/proposed/changes/67631 . The reason given there was "Delete topic; this is way too specific and way too much code for a topic". I'll let animuson elaborate on that himself.
    – Brad Larson Mod
    Jul 29, 2016 at 20:15
  • 19
    Wait.... aren't examples ordered by votes? I think you tried to use documentation for a purpose it really isn't suited for. It's a damned shame, the amount of work you put into it. Perhaps cut down the six parts into a single example and add that to a new topic? Maybe cover relevant bits cut completely out in their own topics, as is appropriate?
    – user1228
    Jul 29, 2016 at 20:18
  • 2
    @BradLarson. Thanks for the assist. :-) Ok, I evidently have no idea what Documentation Topics & Examples are supposted to contain. I've read the Documentation Tour but am still in the dark. So could you briefly explain what belongs in Examples?
    – markE
    Jul 29, 2016 at 20:29
  • 5
    recommended read What, exactly, is Documentation?. Mind you, is probable that you don't get the answer there either.
    – Braiam
    Jul 29, 2016 at 20:30
  • 3
    An example is not intended to be a complete working project. An example is something specific, like a single method. Documentation isn't GitHub
    – 4castle
    Jul 29, 2016 at 20:55
  • 8
    @4castle. I get it...less narrative, less working demo, more pithy code chunks. But I'm still confused about Documentation's scope. I'm fairly good at coding against the htm5-canvas and I assure you the very shortest code example showing how to drag regular & irregular path shapes around the Canvas is 180 lines long. Importantly, Dragging shapes is an extremely common requirement for Canvas coders but the process is complex and requires quite a bit of code to illustrate. Should Examples be out-of-scope if the minimum code length is a couple hundred lines?
    – markE
    Jul 29, 2016 at 21:14
  • 1
    @Will. Thanks ... I've done your suggestion. I pulled just the final (all inclusive) code into a large (but minimally necessary) chunk of code and posted that one Example. I'll see if it is well received.
    – markE
    Jul 29, 2016 at 21:17
  • 15
    @markE "I'm still confused about Documentation's scope" You and everyone else.
    – Mike Cluck
    Jul 29, 2016 at 21:33
  • 2
    @markE Also, that's some really good information. You should consider making it a GitHub repo with a matching GitHub pages site or something.
    – Mike Cluck
    Jul 29, 2016 at 21:42
  • 13
    Clearly they were only thinking of simplistic, toy APIs when they conceived this feature. That is pretty clear in reading answers from the team. If something is too complicated to demonstrate in a throwaway example, then it is simply not a good fit for Docs. Like the x86 instruction set architecture. Or the C++ language. Or, apparently, HTML5 Canvas. Which is a shame, because those are the things that badly need good documentation because it doesn't really exist elsewhere. Instead, we get people duplicating MSDN and showing "Hello world" in Java. :-(
    – Cody Gray Mod
    Jul 30, 2016 at 14:14
  • 5
    @markE - if your work on that topic doesn't end up on Documention, I hope you'll find a place for it (a blog post or series of blog posts). You put a lot of effort into it, and it shouldn't be hidden in a revision history. It should be where someone can find it and use it. Jul 30, 2016 at 16:37
  • 18
    I can't believe such good content got so summarily deleted when Documentation is so full of useless crap. Surely some sort of an improvement request would be a more appropriate action if someone doesn't think content in this form is correct.
    – Alohci
    Jul 30, 2016 at 16:50
  • 2
    @Alohci. Thanks for the kind words :-) It was a moderator who deleted it and they have "immediate kill" capability so there was no notice or review.
    – markE
    Jul 30, 2016 at 17:02
  • 6
    @markE: I totally agree with hatchet. You should put your work--very good job, by the way--in a blog or something, so that other people can benefit from your work.
    – J. Allan
    Jul 30, 2016 at 17:42
  • 3
    ... also, if you remember, please post a link to the blog (or whererever they end up). Those are very good examples, and are the kind of "documentation" I enjoy reading, so I would love to bookmark them once they have a more permanent home. Very surprising they were deleted. Honestly I am just as confused about the scope as everyone else. After coming across a low traffic tag with only 4 topics - 3 of them duplicates of each other (several wrong/poor examples) - I have decided to give up on documentation for now ;-)
    – Leigh
    Jul 30, 2016 at 19:50

1 Answer 1

14

Some explanation would have helped somewhere, in the future that may be nice to have.

For now though, what you produced was not bad content, it was just that the style you used apparently wasn't a good fit for Documentation. If it makes you feel any better I liked the set of examples you created, and am slightly annoyed seeing them deleted although I suppose I can see where it comes from.

In order to move forward, I think it is important to deconstruct your written tutorial. Break it apart into smaller pieces that do not have any duplication, remove the part 1, part 2, etc. aspect and just give in to information not being in a set order (just ready to consume).

Here is a good example imo

https://stackoverflow.com/documentation/javascript/4447/indexeddb#t=201607291908027118461

9
  • 1
  • 1
    @Braiam - Soft deleted, of course. That is how almost everything at the Exchange is. But still, it doesn't show up and aside from this post, is rather hidden from finding.
    – Travis J
    Jul 29, 2016 at 23:13
  • Actually, if you arrive to the topic canonical link you can see there's a box that informs you that you can see the revision prior deletion (which links to further revisions). The asOf=datetimeint seems to be the magic here. And SEO follows links, so in theory the search engines should have found and indexed the topic already.
    – Braiam
    Jul 29, 2016 at 23:15
  • Not indexed yet. I am not sure what the rules for indexing will be, as that is defined by a google algorithm somewhere. I have a good idea though, and to me it seems that this will be buried. If it is not intended to be buried, why "delete" it?
    – Travis J
    Jul 29, 2016 at 23:20
  • Well, you know that nobody is sure about how a topic should look like, but some ideas of how it shouldn't. I think this is one of those "shouldn't".
    – Braiam
    Jul 29, 2016 at 23:45
  • @Braiam. LOL :-) I'm glad I can be the "Example" (pun!) of how not to form a Topic.
    – markE
    Jul 30, 2016 at 0:41
  • 9
    @TravisJ. So do you think the intention of an Example is to be "copy-plug-and-play" code rather than comprehensive documentation. If yes, lets rename "Documentation" to "Snippets".
    – markE
    Jul 30, 2016 at 0:44
  • 2
    @markE did anyone said examples?
    – Braiam
    Jul 30, 2016 at 1:00
  • 1
    @Braiam - You mean Examples?
    – Travis J
    Aug 2, 2016 at 19:30

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