#16779: Add a tutorial for first time Django contributors
---------------------------------------+-------------------------------
Reporter: taavi223 | Owner: taavi223
Type: New feature | Status: new
Milestone: | Component: Documentation
Version: | Severity: Normal
Resolution: | Keywords:
Triage Stage: Accepted | Has patch: 1
Needs documentation: 0 | Needs tests: 0
Patch needs improvement: 1 | Easy pickings: 0
UI/UX: 0 |
---------------------------------------+-------------------------------
Comment (by edunham):
taavi,
It's looking good! Some thoughts on the current version of the document (I
accessed it on http://www.taijala.com/tutorial.html):
* Be explicit about the level of experience (with Python, Django, ticket
trackers, version control...) you expect from the audience -- maybe even
in the first pargraph.
"This tutorial assumes that you've been through the introductory Django
guide at https://docs.djangoproject.com/en/1.3/intro/tutorial01/ and have
some experience with Python [link to tutorial at appropriate level]"
* For the link to "a very powerful search engine" in Trac, it might be
useful to also link an explanation of what the search's fields mean (if
you aren't assuming familiarity with ticket trackers).
https://code.djangoproject.com/wiki/TracTickets#TicketFields would work
ok, but there are probably better tutorials out there.
* In the note starting with "if you're a savvy djangonaut...", place more
emphasis on the "don't install Django with Pip" advice. It would be easy
to overlook in its current format.
* The heading "Actually running the test suite" would be clearer without
the word "actually". The second half of the article appears to actually
have a higher than usual incidence of the word "actually". It might
actually be easier to read if you removed most of the instances or
replaced them with synonyms. Then again, it's actually just my personal
opinion that "actually" can usually be removed without changing a
sentence's meaning and is distracting if you use it too much. :)
* The "Writing a Test for your Ticket" section does a good job of covering
the basics of what one needs to know, but would be even better if it
included some links to external resources on how to design tests, testing
philosophies, or other information.
* Formatting the text of the example differently would make it clearer
which instructions are for any patch and which are for the example ticket
specifically. Perhaps an indent or a change of background color?
* Finally, a table of contents at the top to outline the various sections
will make the organization of the article significantly easier to follow.
Over all, this is looking like an excellent start to the article! Thank
you for putting it together -- it'll be really beneficial to newbies like
me.
-edunham
--
Ticket URL: <https://code.djangoproject.com/ticket/16779#comment:3>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To post to this group, send email to django-updates@googlegroups.com.
To unsubscribe from this group, send email to
django-updates+unsubscr...@googlegroups.com.
For more options, visit this group at
http://groups.google.com/group/django-updates?hl=en.
