Beefy Boxes and Bandwidth Generously Provided by pair Networks
There's more than one way to do things
 
PerlMonks  

Tutorial Acceptance Policy

by hiseldl (Priest)
on Jul 23, 2002 at 14:31 UTC ( [id://184426]=monkdiscuss: print w/replies, xml ) Need Help??

What gives? I posted a Tk Tutorial and it showed up on the Tutorials page at the bottom, and after a week it disappeared. This begs the question, what is the policy for acceptance of a tutorial so that it can be added to the permanent list of tutorials?

I noticed jeffa's tutorial XML::Generator::DBI Tutorial was added to the permanent list a couple days after it was submitted. Which leads me to my next question, do I have to be a high monk in order to get considered for the permanent list?

vroom or one of the other gods please enlighten us on how we get our tutorials approved. Mine was removed from the Tutorial list completely, without cause, without notice, and probably without consideration.

--
hiseldl

Replies are listed 'Best First'.
Re: Tutorial Acceptance Policy
by footpad (Abbot) on Jul 23, 2002 at 15:19 UTC

    Your tutorial was automatically, not deliberately dropped from the list. As you noticed, new tutorials are automatically listed in a section called "Tutorials added in the last week." This section is automatically added to the end of the existing Tutorials page when served by the PM engine.

    Currently, the general process for getting a Tutorial added to the permanent list involves Consideration. Generally, a monk with consideration powers will notice the new tutorial, consider it with a reason similar to "Promote to Tutorials? (Edit eq Yes, Keep eq No)"1 and wait to see what other monks feel about making the new item a permanent part of the tutorials list.

    After a decent period of time, e.g. long enough for a janitor to get a sense of how the promotion voting is going, the node will be added to the Tutorials source or removed from Consideration without further action.

    It's not a formal review process by any means and, like many other editorial decisions on the site, is based more on the experience of the janitor in question than any hard and fast rule. As with other nodes, we try to err on the side of generosity than elitism. Sometimes, simple mistakes get made.

    In your case, it appears that no one considered your node for promotion2 or that I made an error when recently revamping the Tutorials page. If it was the latter, then I apologize.

    I promoted jeffa's tutorial after only a few days primarily because the promotion voting was clearly going in the that direction and it it had a high enough reputation that it was clearly valued by the community at large. (Also, his tutorial was intended to replace an earlier one based on a now deprecated module; thus, his was more of an updated tutorial than brand new material.)

    So, no. You do not have to be a high level monk to get a tutorial listed permanently; however, some general advice for all would-be tutorial writers might include:

    • Make sure your tutorial is well written and clear.

    • Make sure you choose your examples carefully. They have to be simple enough to grok quickly, but they must be more interesting than "hello, foo."

    • Write tutorials that include information beyond the friendly manual.

    • If you must re-write an existing tutorial, then please make sure your final work is clearly needed (e.g. it replaces out-of-date information) or is clearly superior in clarity, coverage, and/or content.

    • Please do *not* include unnecessary HTML formatting. Case in point, I spent about two hours trying to rewite the formatting of a certain tutorial during the recent revamp primarily because the original author posted an entire HTML document, instead of just the rendered <body> content.

    • Remember Hanlon's Razor

    --f

    Update: P.S. Looks like VSarkiss types more quickly than I do. And more concisely. ;-)

    Footnotes:


    1 - Yes, it's a hack. We may change that at some point. If there's time and we manage to get everything else done that we need/want to do.

    2 - This has now been corrected. We'll see how the promotion voting goes.


     
Re: Tutorial Acceptance Policy
by VSarkiss (Monsignor) on Jul 23, 2002 at 14:47 UTC

    without cause, without notice, and probably without consideration
    Also without malice. Good brother footpad spent a long time re-organizing and cleaning up the Tutorials front page as described in Updating the Tutorials Node. Far more likely that one just fell through the cracks.

    Though he may sometimes appear divine, footpad is human like the rest of us. Considering how strongly he feels about abuse of editorial powers, I can't imagine him dropping a tutorial on purpose without talking to everyone else first. If nothing else, you would have received a /msg.

    Update
    In regards to your second question, no, there is no level requirement for submitting a tutorial (or book or module review).

    Update 2
    I just checked, and your node is on the list of nodes to consider (read footpad's writeup to understand why it's there) and has two "yes" votes for being promoted to tutorials.

Re: Tutorial Acceptance Policy
by hiseldl (Priest) on Jul 23, 2002 at 15:39 UTC
    VSarkiss and footpad, thank you for your quick responses! It's great that we have a process for approving tutorials, even if it is semi-formal. I would like to recommend putting a link at the top of the tutorials page with footpad's comments:

    Currently, the general process for getting a Tutorial added to the permanent list involves Consideration. Generally, a monk with consideration powers will notice the new tutorial, consider it with a reason similar to "Promote to Tutorials? (Edit eq Yes, Keep eq No)"1 and wait to see what other monks feel about making the new item a permanent part of the tutorials list.

    After a decent period of time, e.g. long enough for a janitor to get a sense of how the promotion voting is going, the node will be added to the Tutorials source or removed from Consideration without further action.

    It's not a formal review process by any means and, like many other editorial decisions on the site, is based more on the experience of the janitor in question than any hard and fast rule. As with other nodes, we try to err on the side of generosity than elitism. Sometimes, simple mistakes get made.

    You do not have to be a high level monk to get a tutorial listed permanently; however, some general advice for all would-be tutorial writers might include:

    • Make sure your tutorial is well written and clear.
    • Make sure you choose your examples carefully. They have to be simple enough to grok quickly, but they must be more interesting than "hello, foo."
    • Write tutorials that include information beyond the friendly manual.
    • If you must re-write an existing tutorial, then please make sure your final work is clearly needed (e.g. it replaces out-of-date information) or is clearly superior in clarity, coverage, and/or content.
    • Please do *not* include unnecessary HTML formatting. Case in point, I spent about two hours trying to rewite the formatting of a certain tutorial during the recent revamp primarily because the original author posted an entire HTML document, instead of just the rendered <body> content.

    This would, imho, alleviate future confusion. :-)

    --
    hiseldl

Log In?
Username:
Password:

What's my password?
Create A New User
Domain Nodelet?
Node Status?
node history
Node Type: monkdiscuss [id://184426]
Approved by osfameron
Front-paged by wil
help
Chatterbox?
and the web crawler heard nothing...

How do I use this?Last hourOther CB clients
Other Users?
Others contemplating the Monastery: (6)
As of 2024-03-28 11:26 GMT
Sections?
Information?
Find Nodes?
Leftovers?
    Voting Booth?

    No recent polls found