Re: Django documentation for newer users

[Emre Yılmaz]

although it is not the best, django is well documented imo. (my
favorite after php manual)

browsing the source is not bad at all when the documentation is not
enough for the developer. you become more familiar to the django if
you dive in to the source. it is very handy when you need some
hacking.


On 3/5/10, stherrien  wrote:
> Exactly my point docs need to be more organization to be constructive
> for django users.
>
> On Mar 5, 11:05 am, Jared Forsyth  wrote:
>> To be honest I am quicker to just go to django's source code rather than
>> the
>> docs, as often I can find what I need there, and the docs aren't (imo)
>> organized enough to provide much of an advantage.
>>
>> On Fri, Mar 5, 2010 at 8:46 AM, stherrien  wrote:
>> > Hi all,
>>
>> > I have a request that django documentation show the import locations
>> > for classes like in other well formed docs found on the web showing
>> > the users where the classes can be found for import. I think this
>> > would be handy for newer users and experienced users finding something
>> > new. Documentation on the site is different from page to page. Take
>> > for instance the file object doc page in django doesn't tell the user
>> > where this can be imported which requires you to dig into the python
>> > help pages to try and find it. which is "from django.core.files.base
>> > import File". it would be nice to show this consistently across the
>> > site. I would be happy to help make this happen.
>>
>> > -shawn
>>
>> > --
>> > You received this message because you are subscribed to the Google
>> > Groups
>> > "Django developers" group.
>> > To post to this group, send email to django-develop...@googlegroups.com.
>> > To unsubscribe from this group, send email to
>> > django-developers+unsubscr...@googlegroups.com
>> > .
>> > For more options, visit this group at
>> >http://groups.google.com/group/django-developers?hl=en.
>
> --
> You received this message because you are subscribed to the Google Groups
> "Django developers" group.
> To post to this group, send email to django-develop...@googlegroups.com.
> To unsubscribe from this group, send email to
> django-developers+unsubscr...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/django-developers?hl=en.
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: Django documentation for newer users

[stherrien]

Your right the docs are there and they are very useful I think. I
missed a few things when opening this ticket let me be more precise I
would like to see the module index at the top of the actually module
doc page. The module index's are offered as separate link on the docs
page which lists the available modules which is helpful. if we can add
this to the actual page you hit when clicking the link would be very
helpful.

On Mar 5, 11:42 am, Karen Tracey  wrote:
> On Fri, Mar 5, 2010 at 11:40 AM, Karen Tracey  wrote:
> > ... open a ticket and attach the patch.
>
> And, as for all other tickets, it'll help if you search the tracker first
> and make sure that whatever ticket you're planning on opening isn't already
> open.
>
> Karen

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: Django documentation for newer users

[Waylan Limberg]

On Fri, Mar 5, 2010 at 11:35 AM, stherrien  wrote:
> What I'm suggesting is that we setup something to allow everyone to
> improve the docs with help from the core django group. I think this
> would be very helpful to everyone. if one of the core group would like
> to help us get setup to do this it would be great. maybe if they setup
> a repository with the current online docs online so we can add updates
> as we do with django itself.

So everyone else already answered your concern above,

Anyway, regarding your first question, see the "Global Module Index".
It contains full import paths to each module and links to the docs for
that module wherever they may be (howtos, ref, etc). But yeah, the
individual docs should probably include import paths as well.

http://docs.djangoproject.com/en/1.1/modindex/

As far as general organization goes, the "Table of Contents" is more
helpful imo. I see the front page as more of a highlight of
interesting things intended for those taking their first look at the
project, but the table of contents gives a much better overview of how
everything is actually organized by document section etc. The urls
even match the pattern used here, and the "next" and "previous" links
follow the order of documents here.

http://docs.djangoproject.com/en/1.1/contents/

Both are linked to from every doc page in the sidebar to the right (In
the "Browse" section).

>
> On Mar 5, 11:20 am, stherrien  wrote:
>> Exactly my point docs need to be more organization to be constructive
>> for django users.
>>
>> On Mar 5, 11:05 am, Jared Forsyth  wrote:
>>
>> > To be honest I am quicker to just go to django's source code rather than 
>> > the
>> > docs, as often I can find what I need there, and the docs aren't (imo)
>> > organized enough to provide much of an advantage.
>>
>> > On Fri, Mar 5, 2010 at 8:46 AM, stherrien  wrote:
>> > > Hi all,
>>
>> > > I have a request that django documentation show the import locations
>> > > for classes like in other well formed docs found on the web showing
>> > > the users where the classes can be found for import. I think this
>> > > would be handy for newer users and experienced users finding something
>> > > new. Documentation on the site is different from page to page. Take
>> > > for instance the file object doc page in django doesn't tell the user
>> > > where this can be imported which requires you to dig into the python
>> > > help pages to try and find it. which is "from django.core.files.base
>> > > import File". it would be nice to show this consistently across the
>> > > site. I would be happy to help make this happen.
>>
>> > > -shawn
>>
>> > > --
>> > > You received this message because you are subscribed to the Google Groups
>> > > "Django developers" group.
>> > > To post to this group, send email to django-develop...@googlegroups.com.
>> > > To unsubscribe from this group, send email to
>> > > django-developers+unsubscr...@googlegroups.com
>> > > .
>> > > For more options, visit this group at
>> > >http://groups.google.com/group/django-developers?hl=en.
>
> --
> You received this message because you are subscribed to the Google Groups 
> "Django developers" group.
> To post to this group, send email to django-develop...@googlegroups.com.
> To unsubscribe from this group, send email to 
> django-developers+unsubscr...@googlegroups.com.
> For more options, visit this group at 
> http://groups.google.com/group/django-developers?hl=en.
>
>



-- 

\X/ /-\ `/ |_ /-\ |\|
Waylan Limberg

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: Django documentation for newer users

[Peter Herndon]

On Mar 5, 2010, at 11:35 AM, stherrien wrote:

> What I'm suggesting is that we setup something to allow everyone to
> improve the docs with help from the core django group. I think this
> would be very helpful to everyone. if one of the core group would like
> to help us get setup to do this it would be great. maybe if they setup
> a repository with the current online docs online so we can add updates
> as we do with django itself.


There are a couple of relevant pages on how to work with the documentation:

http://docs.djangoproject.com/en/1.1/internals/contributing/#documentation-style

http://docs.djangoproject.com/en/1.1/internals/documentation/#internals-documentation

Feel free to check out the project, make changes, file bug reports, and submit 
patches.  Documentation quality is taken pretty darned seriously, from what 
I've seen.

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: Django documentation for newer users

[Karen Tracey]

On Fri, Mar 5, 2010 at 11:40 AM, Karen Tracey  wrote:

> ... open a ticket and attach the patch.
>
>
And, as for all other tickets, it'll help if you search the tracker first
and make sure that whatever ticket you're planning on opening isn't already
open.

Karen

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: Django documentation for newer users

[Alex Gaynor]

Uhh... the documentation is part of djangos repository, along with all of
the code. It has long been django's policy to treat docs contributios the
same as code contributios.

Alex

On Mar 5, 2010 11:35 AM, "stherrien"  wrote:

What I'm suggesting is that we setup something to allow everyone to
improve the docs with help from the core django group. I think this
would be very helpful to everyone. if one of the core group would like
to help us get setup to do this it would be great. maybe if they setup
a repository with the current online docs online so we can add updates
as we do with django itself.


On Mar 5, 11:20 am, stherrien  wrote:
> Exactly my point docs need to be m...

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: Django documentation for newer users

[Sean O'Connor]

The Django documentation is already included in code base with Django and
anybody is welcome to submit patches for them.  If you do a checkout of
Django, there will be a "docs" directory there.  Inside there is the full
documentation source in reStructuredText.  If you'd like a local HTML or PDF
version of the docs you can simply install sphinx[1] on your machine and
build the docs like any other sphinx project.

If your interested in learning more I'd recommend that you read the "How the
Django Documentation Works"[2] page as well as "Contributing to Django"[3].


Sean O'Connor
http://seanoc.com

[1] http://sphinx.pocoo.org/
[2]
http://docs.djangoproject.com/en/1.1/internals/documentation/#internals-documentation

[3]
http://docs.djangoproject.com/en/1.1/internals/contributing/#internals-contributing


On Fri, Mar 5, 2010 at 11:35 AM, stherrien  wrote:

> What I'm suggesting is that we setup something to allow everyone to
> improve the docs with help from the core django group. I think this
> would be very helpful to everyone. if one of the core group would like
> to help us get setup to do this it would be great. maybe if they setup
> a repository with the current online docs online so we can add updates
> as we do with django itself.
>
> On Mar 5, 11:20 am, stherrien  wrote:
> > Exactly my point docs need to be more organization to be constructive
> > for django users.
> >
> > On Mar 5, 11:05 am, Jared Forsyth  wrote:
> >
> > > To be honest I am quicker to just go to django's source code rather
> than the
> > > docs, as often I can find what I need there, and the docs aren't (imo)
> > > organized enough to provide much of an advantage.
> >
> > > On Fri, Mar 5, 2010 at 8:46 AM, stherrien 
> wrote:
> > > > Hi all,
> >
> > > > I have a request that django documentation show the import locations
> > > > for classes like in other well formed docs found on the web showing
> > > > the users where the classes can be found for import. I think this
> > > > would be handy for newer users and experienced users finding
> something
> > > > new. Documentation on the site is different from page to page. Take
> > > > for instance the file object doc page in django doesn't tell the user
> > > > where this can be imported which requires you to dig into the python
> > > > help pages to try and find it. which is "from django.core.files.base
> > > > import File". it would be nice to show this consistently across the
> > > > site. I would be happy to help make this happen.
> >
> > > > -shawn
> >
> > > > --
> > > > You received this message because you are subscribed to the Google
> Groups
> > > > "Django developers" group.
> > > > To post to this group, send email to
> django-develop...@googlegroups.com.
> > > > To unsubscribe from this group, send email to
> > > > django-developers+unsubscr...@googlegroups.com
> 
> >
> > > > .
> > > > For more options, visit this group at
> > > >http://groups.google.com/group/django-developers?hl=en.
>
> --
> You received this message because you are subscribed to the Google Groups
> "Django developers" group.
> To post to this group, send email to django-develop...@googlegroups.com.
> To unsubscribe from this group, send email to
> django-developers+unsubscr...@googlegroups.com
> .
> For more options, visit this group at
> http://groups.google.com/group/django-developers?hl=en.
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: Django documentation for newer users

[Gary Reynolds]

That's interesting, I'm of the other belief... I find the Django
documentation to be thorough and organised very well.

One of the main reasons I (and I am sure countless others) even started
using Django was because of it's excellent documentation.

As the project has matured from version 0.96 onwards I believe that this has
not only continued to hold true, but has even improved over time. The strong
emphasis on provided good documentation with any patch has definitely
fostered this.

I think the old addage "if it ain't broke, don't fix it" best describes this
- for many people the documentation works not just fine, but damn well... if
you think it needs an overhaul, I'd like to first of all know what you
intend to change/add it to make it better.

On Fri, Mar 5, 2010 at 4:20 PM, stherrien  wrote:

> Exactly my point docs need to be more organization to be constructive
> for django users.
>
> On Mar 5, 11:05 am, Jared Forsyth  wrote:
> > To be honest I am quicker to just go to django's source code rather than
> the
> > docs, as often I can find what I need there, and the docs aren't (imo)
> > organized enough to provide much of an advantage.
> >
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: Django documentation for newer users

[Karen Tracey]

On Fri, Mar 5, 2010 at 11:35 AM, stherrien  wrote:

> What I'm suggesting is that we setup something to allow everyone to
> improve the docs with help from the core django group. I think this
> would be very helpful to everyone. if one of the core group would like
> to help us get setup to do this it would be great. maybe if they setup
> a repository with the current online docs online so we can add updates
> as we do with django itself.
>
>
Docs are already in the repository. If you've got an SVN checkout they're
all in the docs subtree off the root. The tracker has a "Documentation"
component. If you've got a specific suggestion for improvement, go ahead and
make the changes in your local checkout, generate a diff as you would for
code, open a ticket and attach the patch.

Karen

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: Django documentation for newer users

[stherrien]

What I'm suggesting is that we setup something to allow everyone to
improve the docs with help from the core django group. I think this
would be very helpful to everyone. if one of the core group would like
to help us get setup to do this it would be great. maybe if they setup
a repository with the current online docs online so we can add updates
as we do with django itself.

On Mar 5, 11:20 am, stherrien  wrote:
> Exactly my point docs need to be more organization to be constructive
> for django users.
>
> On Mar 5, 11:05 am, Jared Forsyth  wrote:
>
> > To be honest I am quicker to just go to django's source code rather than the
> > docs, as often I can find what I need there, and the docs aren't (imo)
> > organized enough to provide much of an advantage.
>
> > On Fri, Mar 5, 2010 at 8:46 AM, stherrien  wrote:
> > > Hi all,
>
> > > I have a request that django documentation show the import locations
> > > for classes like in other well formed docs found on the web showing
> > > the users where the classes can be found for import. I think this
> > > would be handy for newer users and experienced users finding something
> > > new. Documentation on the site is different from page to page. Take
> > > for instance the file object doc page in django doesn't tell the user
> > > where this can be imported which requires you to dig into the python
> > > help pages to try and find it. which is "from django.core.files.base
> > > import File". it would be nice to show this consistently across the
> > > site. I would be happy to help make this happen.
>
> > > -shawn
>
> > > --
> > > You received this message because you are subscribed to the Google Groups
> > > "Django developers" group.
> > > To post to this group, send email to django-develop...@googlegroups.com.
> > > To unsubscribe from this group, send email to
> > > django-developers+unsubscr...@googlegroups.com
> > > .
> > > For more options, visit this group at
> > >http://groups.google.com/group/django-developers?hl=en.

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: Django documentation for newer users

[stherrien]

Exactly my point docs need to be more organization to be constructive
for django users.

On Mar 5, 11:05 am, Jared Forsyth  wrote:
> To be honest I am quicker to just go to django's source code rather than the
> docs, as often I can find what I need there, and the docs aren't (imo)
> organized enough to provide much of an advantage.
>
> On Fri, Mar 5, 2010 at 8:46 AM, stherrien  wrote:
> > Hi all,
>
> > I have a request that django documentation show the import locations
> > for classes like in other well formed docs found on the web showing
> > the users where the classes can be found for import. I think this
> > would be handy for newer users and experienced users finding something
> > new. Documentation on the site is different from page to page. Take
> > for instance the file object doc page in django doesn't tell the user
> > where this can be imported which requires you to dig into the python
> > help pages to try and find it. which is "from django.core.files.base
> > import File". it would be nice to show this consistently across the
> > site. I would be happy to help make this happen.
>
> > -shawn
>
> > --
> > You received this message because you are subscribed to the Google Groups
> > "Django developers" group.
> > To post to this group, send email to django-develop...@googlegroups.com.
> > To unsubscribe from this group, send email to
> > django-developers+unsubscr...@googlegroups.com
> > .
> > For more options, visit this group at
> >http://groups.google.com/group/django-developers?hl=en.

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.

Re: Django documentation for newer users

[Jared Forsyth]

To be honest I am quicker to just go to django's source code rather than the
docs, as often I can find what I need there, and the docs aren't (imo)
organized enough to provide much of an advantage.

On Fri, Mar 5, 2010 at 8:46 AM, stherrien  wrote:

> Hi all,
>
>
> I have a request that django documentation show the import locations
> for classes like in other well formed docs found on the web showing
> the users where the classes can be found for import. I think this
> would be handy for newer users and experienced users finding something
> new. Documentation on the site is different from page to page. Take
> for instance the file object doc page in django doesn't tell the user
> where this can be imported which requires you to dig into the python
> help pages to try and find it. which is "from django.core.files.base
> import File". it would be nice to show this consistently across the
> site. I would be happy to help make this happen.
>
>
> -shawn
>
> --
> You received this message because you are subscribed to the Google Groups
> "Django developers" group.
> To post to this group, send email to django-develop...@googlegroups.com.
> To unsubscribe from this group, send email to
> django-developers+unsubscr...@googlegroups.com
> .
> For more options, visit this group at
> http://groups.google.com/group/django-developers?hl=en.
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers" group.
To post to this group, send email to django-develop...@googlegroups.com.
To unsubscribe from this group, send email to 
django-developers+unsubscr...@googlegroups.com.
For more options, visit this group at 
http://groups.google.com/group/django-developers?hl=en.