Beefy Boxes and Bandwidth Generously Provided by pair Networks
Clear questions and runnable code
get the best and fastest answer

Rethinking Tutorials

by gmax (Abbot)
on Jan 08, 2005 at 14:14 UTC ( #420528=monkdiscuss: print w/replies, xml ) Need Help??


There is a long list of consideration actions for Security techniques every programmer should know. Among other things, there is the following:

Considered by kutsu: "Edit: Move to tutorials" Vote: 4/10/0
Unconsidered by davido: Juerd knows where to post tutorials. He chose to post this as a Meditation. Let's respect the author's decision.

Was it really the author's decision? Perhaps it was in that particular case, but I believe that in a more general way this may not be the truth.

The current situation

Let's not get into the specific reasons why that particular node was fit or unfit for becoming a Tutorial, and let's consider what really happens when you achieve some expertise in a particular field, and you want to share it with other people in a tutorial. You have basically two ways:

  • You write under the Tutorials section, and that's it.
  • You write under Meditations, and then, if somebody sees it fit, your node will be considered as a tutorial, and if it gets enough votes, it will eventually be moved to Tutorials.

It sounds reasonable. In the first case, it is the will of the author to write a tutorial, and in the second case, the node becomes a tutorial by popular will.

Uhmm. What's wrong with this picture? Here's what really happens:

  1. You post a node in Tutorials. It will get some exposure to all in Newest Nodes, perhaps it will get lots of upvotes. And then it will vanish.
  2. You post a node in Meditations. It will be considered to be moved to Tutorials, and it will get voted 11/29/0, and then somebody will unconsider it because there is no consensus and the node blends with the rest of Meditations and stay in the heap.

Surprised about the first case? You should. Using Super Search (apparently the only way of finding these stray tutorials, you will get, to see only a few, the following nodes, which have received quite a lot of popular favor (= upvotes) but are out of sight.

brian_d_foyPerl documentation documentation
DigitalKittyRecursion: The Towers of Hanoi problem
JuerdIncluding files

Despite being well written and well received by the community, those nodes are NOT in Tutorials.
(update At least they weren't there until Arunbear's action.)

To be there, somebody must ask the editors to do something, and eventually some of those nodes that were born that way will find their way to the Tutorials page. But if the author doesn't know, or doesn't care about pushing through this lengthy procedure, those valuable nodes stay in the shadow.


You may think that a simple solution would be to publish immediately the nodes in Tutorials, so the deserving ones will stay there forever, easy to grasp for the needs of any beginner. Yes. But unfortunately this solution would keep in plain view also those would-be tutorials which are not up to PerlMonks standards.

Moreover, the nodes published in Tutorials suffer from another problem: they can't be frontpaged. What's wrong with that? You may naively think. After all, if they are Tutorials, they are forever in plain view. Not so. If you publish a would-be tutorial, and it gets only 20 votes, it would be hard for an editor to justify the fix. But if you have published that node during a weekend (and it seems only fit, because during the weekend you have time to spare) your node has a limited exposure of 24 hours in the least active period of the week, without many chances of getting the attention it deserves. At least, if it were in the front page, it would receive some more attention, and a request to carve its title to the Tutorials page would be honored much more easily.

So the situation is that the ones that should be our most prized nodes are neglected by the system, making it quite difficult for a well written tutorial to get the recognition it deserves.


At the end of my research, I should propose something, so here goes:

  • Nodes posted under Tutorials should end up published under Meditations, with an automatic consideration note saying "move to Tutorials - edit=yes keep=no".
  • The move to tutorials should happen if the node gets at least X edit - keep votes and Y reputation votes, where X and Y should be a reasonable amount. I's say X=20 and Y = 40. Perhaps we should also state how many days at most the node should stay in nodes to consider before it is definitely rejected. I'd say three weeks).
  • Nodes that don't reach the consensus should be marked clearly as such (eg. "tutorial candidate - not accepted - votes: #/#/#"), to make it easy to find.
  • Nodes with negative rep ( < -5 ) should be unconsidered and treated as normal Meditations nodes.

But of course, if there are other ways that will blend better with the existing PM code, let's hear them. The goal to reach is to establish an easy mechanism to clearly publish (or reject) Tutorials.

See also Updating the Tutorials Node.

I like castaway's solution. It seems to have all the elements I was asking for. (Provided that tutorials get through the approval system like SOPWs and Meditations). Actually I like it more than my own. Thanks.

 _  _ _  _  
(_|| | |(_|><

Replies are listed 'Best First'.
Re: Rethinking Tutorials
by castaway (Parson) on Jan 09, 2005 at 09:35 UTC
    We were in fact considering this exact problem yesterday. While I like your description of it, I don't like your solution. our solution would be as follows:
    • Tutorials get posted to tutorials, as it should be, the author can pick a tutorial category when posting.
    • The Tutorials page automagically lists ALL tutorials, according to the picked category, possibly with a section for NEW posts, or some way of identifying them.
    • Tutorials can be front-paged (I can't see a reason why they shouldn't be.)
    • Tutorials can be considered to be moved away from that section, and get moved by editors if need be.
    • Tutorials can also be moved between categories by the editors
    • Categories would be maintained by the editors, suggestions could be made via /msg editors, Editor Requests or maybe a new page for that purpose.
    In my perfect world, also, each tutorial would be maintained by its author, or the editors, a little like Q&A, so corrections and updates would be made as they are needed, keeping teh the tutorial as useful as possile.

    Further thought: Each tutorial should also mention which perl versions it applie(s|d) to at time of writing, and which operating systems, if appropriate.

    In case you didn't know, the only real problem with the current system is, that Tutorial type nodes have to be added to the Tutorials page by hand. Thus, even if a Meditation gets 'moved' to Tutorials, all that actually happens is that its nodetype gets changed to 'perltutorial', it won't turn up on the Tutorials page unless the editor goes and does that as well. (And I'll admit, I've never added any).


    Update: The reason that Meditations that have been considered as 'Move to Tutorials' are getting unconsidered recently, is that we are in general, not moving Meditations to Tutorials any more. This is mostly because quite a few are getting considered that weren't intended as tutorials, and aren't very good as tutorials. (So we need to educate people that intended to write a tutorial, to post them there, even if not quite finished.. It's easy write 'under construction' on a post, and to update one)

      I also don't mind if people post nodes to Meditations that are meditative which then result in replies being taken into consideration and an updated version being posted as a Tutorial. While many Meditations are informative and well written, most of them are not tutorials and don't fit in a section called "Tutorials" (where people expect to find material that tutors them, not just every node ever written that is informative). So I think the authors should be moving nodes to Tutorials by republishing them not by having the first draft and a bunch of replies just dumped into the Tutorials section.

      I'm not a great fan of trashing the careful organization of tutorials to replace it with just listing all tutorial grouped into sections. I think we should keep both, the organized list of tutorials maintained by janitors (and SiteDocClan though I don't think they have access to do so yet) and also plain lists of all tutorials by section and sorted by reputation.

      The we have the historic problem of a bunch of nodes that are in the Meditations section but are linked to from the Tutorials page. This makes finding such information via Super Search confusing. That is another reason why I like having a first draft in Meditations and, if it is well enough received, have an improved version in Tutorials and, of course, each should end up containing a link to the other. Then people can search for something they remember seeing in Meditations or they can search for Tutorial information.

      - tye        

        I like the idea listing all tutorials. Though two version of them, I prefer.

        One version is the editor approved and official tutorials.

        the other ones are submitted and not yet approved. these tutorials should be listed in different categories and in an order of the most voted to the least voted (show top 20 then click here to view more kinda way ?). that way, the most helpful tutorials are listed on top and get higher consideration for official tutorial.

        me and few chinese perl users are setting up similar system and perlmonks is giving me a lot of idea about how to organize the site in order to make it useful.

      Tutorials can be considered to be moved away from that section, and get moved by editors if need be.

      I believe you mean well by your proposal, but I am afraid that this could be unrealistic.

      I tested your statement yesterday. I considered this would-be tutorial for moving to Meditations, because it is clear from its reputation (it was negative when I considered) and from the comments added by knowledgeable monks, that the proposal had several serious flaws.

      There is no consensus in the consideration, though. 6 people voted for keeping it, and the reasons why someone would want to keep a flawed (and possibly misleading) document as a tutorial is really beyond me.

      I may make some assumptions to explain that. I may assume that people don't bother reading the comments, and from my request it just seemed that I was a snotty SOB who wanted to punish a tutorial that I didn't like. I may assume that people here don't like censoring, and this kind of node moving may sound like censoring, therefore the naturally kind monks voted for keeping.

      This is just some more food for your thoughts. Please take it into consideration when cooking the final solution.

Re: Rethinking Tutorials
by Limbic~Region (Chancellor) on Jan 08, 2005 at 17:13 UTC
Re: Rethinking Tutorials
by Arunbear (Parson) on Jan 08, 2005 at 16:00 UTC
Re: Rethinking Tutorials
by eyepopslikeamosquito (Chancellor) on Jan 10, 2005 at 03:56 UTC

    Was it really the author's decision? Perhaps it was in that particular case, but I believe that in a more general way this may not be the truth.
    Last week, I noticed that Writing Solid CPAN Modules was considered to be moved to Tutorials. Despite having been a monk for two years, I was, cough, hardly aware of the Tutorials section and it never occurred to me to post it there! So, I was pleased to learn about this possibility and will consider posting there next time.

    On reflection, I agree with tye that many meditations (including mine) are not complete or detailed enough to be a tutorial, but could be polished up to a high enough standard with some extra effort from the author and especially by incorporating the feedback got from the meditation.

      In defense of the "The author chose to post to Meditations, let's respect that" attitude, broaden that beyond the simple Tutorials discussion:

      • If an author chooses not to use active links when providing a URL, should Janitors linkify the URL?
      • If an author chooses not to activate links to POD when mentioned, should Janitors add this functionality to the node in the author's behalf?
      • If an author chooses not to pod-linkify instances of Perl function names (eg. chooses not to turn 'print' into [doc://print]), should we be changing that too?
      • If an author makes a spelling error in the body of a node, should we fix that for them?
      • If an author is a non-english speaker should we repair his grammar to make the node more understandable?
      • If we think an author's question or meditation could be worded better, should we change it?
      • If an author who has been here at the monastery for several years, and who has participated to the extent that (s)he has become a saint, and that author posts a Meditation, and if that post is clearly ON-TOPIC as a meditation, should we presume to know the author's intent better than (s)he does, and vote to move his/her post into Tutorials?

      It is my belief that in most cases, the answer to these questions is no. We shouldn't take it upon ourselves to change nodes unless something is actually broken.

      Janitors fix things like formatting, unsearchable titles, profanity, broken tags, broken links, move posts out of sections where they're off-topic, into sections where they're on-topic (eg., from PMDiscussion to SoPW), and this sort of cleanup maintenance. But Janitors don't write nodes for people, fix their spelling and grammar, improve clarity in language, or haphazardly move nodes from one on-topic section to another on-topic section. Janitors don't presume to know better than the author, with respect to content or placement, unless placement of a node is clearly in error. If a well-established monk chooses to post a Meditation, what right do we all have to force it to be a Tutorial instead? And if it was posted as a meditation accidentally, that author can easily /msg the Janitors requesting a move into Tutorials.

      Many things can and should simply be accomplished by sending a /msg to an author. In the case of "promote to tutorials", it would be much better for an author to take the content of his/her meditation, and work it themselves, in their own words and style, into a real tutorial, and then post this newly reworked article as a tutoral. If someone's meditation is something that is close to being a great tutorial, /msg the author asking him or her to work it up into one and post it. Many people will respond favorably to such requests.


        Reply saved as draft.

Re: Rethinking Tutorials
by kutsu (Priest) on Jan 21, 2005 at 21:05 UTC

    Not really in regards to gmax specifically (or anyone else) but just to point out: Juerd considered Security techniques every programmer should know himself after it had been unconsidered...this leads me to believe I was right in my reading of the intent of that post. I also considered it for Tutorials because it has been my experience that many monks (even ones who have been here for quite a while) forget or don't know that we have a Tutorials section or that they can post there and I have seen a few Meditations be considered for moving to Tutorials (and more importantly seen no documentation saying site policy is against this). Again this is directed at no single person, meant solo to express my reasons.

    "Cogito cogito ergo cogito sum - I think that I think, therefore I think that I am." Ambrose Bierce

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: monkdiscuss [id://420528]
Approved by mowgli
Front-paged by mowgli
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others about the Monastery: (5)
As of 2017-01-23 01:26 GMT
Find Nodes?
    Voting Booth?
    Do you watch meteor showers?

    Results (190 votes). Check out past polls.