documentation re-factor for 1.3?
dffdgsdfgsdfhjhtre
(articles explaining all about one specific object such as slugify or
the Feed class), and "topical" documentation (articles explaining how
to do stuff like write templates).
It seems right now, django's documentation is trying to do both at the
same time. One project that does reference documentation really well,
imo, is PHP. For example: http://us3.php.net/preg_replace Say what you
will about PHP, but it's documentation for each function it provides
is top notch. I really wish django had something like that for each
function it provides.
Yesterday I wanted to add the RegexValidator to my project, but
couldn't figure out how to import it because the documentation didn't
mention where the validators lives. I had to resort to googling
"RegexValidator django import" and came across some random pastebin
which had the import, and then went from there. That wasn't the first
time I had to do this.
I think what we should so is totally revamp the documentation for the
1.3 release. I'm willing to do most of the work. I shouldn't be too
hard to do because right now everything is mostly already written,
just not organized very well.
Right now the documentation consists of a relatively small number of
pages that are sometimes 50 or 60 screens long (obviously depending on
screen resolution). What I think it better is to have a much larger
number of pages, each only being 10 screens long max. One page for
each model field, one page for each widget type, one page for each
template tag, etc. Then each page can link to the corresponding
"topical" documentation page to see how that function/class/object
relates to the big picture.
Has there been any real discussion on how to move the documentation
forward? I know there has been murmurs over the years on how django's
documentation is in need of some organizing...
Here are some quick and dirty examples of what I'm thinking about:
http://pastebin.com/Cp2FK34V
http://pastebin.com/ZQQ4z9B9
James Bennett
> It seems right now, django's documentation is trying to do both at the
> same time. One project that does reference documentation really well,
> imo, is PHP. For example: http://us3.php.net/preg_replace Say what you
> will about PHP, but it's documentation for each function it provides
> is top notch. I really wish django had something like that for each
> function it provides.
Django doesn't have that, but Python does: it's called epydoc and it
will happily generate for you a javadoc-style interface for browsing
every module, class and function.
--
"Bureaucrat Conrad, you are technically correct -- the best kind of correct."
Flávio Amieiro
There are two types of documentation, "reference" documentation
(articles explaining all about one specific object such as slugify or
the Feed class), and "topical" documentation (articles explaining how
to do stuff like write templates).
It seems right now, django's documentation is trying to do both at the
same time.
I agree that sometimes django's documentation can be a mixture of those two
One project that does reference documentation really well,
imo, is PHP. For example: http://us3.php.net/preg_replace Say what you
will about PHP, but it's documentation for each function it provides
is top notch. I really wish django had something like that for each
function it provides.
Yesterday I wanted to add the RegexValidator to my project, but
couldn't figure out how to import it because the documentation didn't
mention where the validators lives. I had to resort to googling
"RegexValidator django import" and came across some random pastebin
which had the import, and then went from there. That wasn't the first
time I had to do this.
I think what we should so is totally revamp the documentation for the
1.3 release. I'm willing to do most of the work. I shouldn't be too
hard to do because right now everything is mostly already written,
just not organized very well.
dffdgsdfgsdfhjhtre
> For this kind of problem, i just grep django's code for the string I want. I
> know that not everyone likes to do this
never, ever, ever be an acceptable substitution for proper
documentation.
> I'm not saying the organization of the documentation can't be improved, but
> I really don't see the point of having this kind of auto generated
> documentation when we have great docstrings and resources to access them.
for there being no documentation at all. Should we just put everything
into docstrings and tell people to use epydoc and help()?
Flávio Amieiro
I may be in the minority here, but I believe grepping source should
never, ever, ever be an acceptable substitution for proper
documentation.
Then how else should the docs be re-organized? You seem to be arguing
for there being no documentation at all. Should we just put everything
into docstrings and tell people to use epydoc and help()?
dffdgsdfgsdfhjhtre
documentation usually sucks. What I'm wanting to do is remove all the
reference stuff and move it into it's own section so that the topical
documentation can be more specialized and concise.
There are three types of users of django: Beginners, intermediate, and
experts. We should reorganize the documentation to target each type.
Beginners who know programming and python well, but don't know Django.
These people will need the topical documentation the most because it
will explain to them the entire process from a birds eye perspective.
Then there are the intermediate users, such as myself, who already
know how templates work, how urls are resolved, etc. We don't need the
topical documentation as much because we already know that stuff. What
we do need is reference. I don't know about you all, but I always have
to look up the model field parameters every time I write a model
because I can never remember them. Right now I have to load up this
page: http://docs.djangoproject.com/en/1.2/ref/models/fields/#ref-models-fields
then wade through a ton of stuff because th stuff I'm looking for is
mixed with paragraphs and paragraphs of text.
Then there are the experts. The core developers and the people who
delve in and modify django code itself. Doc strings and "#"
documentation should be written for them. Epydoc should be what these
people use. They already know what a bit of code does, what is
important to them, is how the code worlks. Why a certain under-the-
hood metaclass does what it does.
Luke Plant
> There are two types of documentation, "reference" documentation
> (articles explaining all about one specific object such as slugify or
> the Feed class), and "topical" documentation (articles explaining how
> to do stuff like write templates).
>
> It seems right now, django's documentation is trying to do both at the
> same time. One project that does reference documentation really well,
> imo, is PHP. For example: http://us3.php.net/preg_replace Say what you
> will about PHP, but it's documentation for each function it provides
> is top notch. I really wish django had something like that for each
> function it provides.
Unlike PHP, we have namespaces, which means that providing a list of
every function/class is a different matter. But we already do it:
http://docs.djangoproject.com/en/dev/genindex/
> Yesterday I wanted to add the RegexValidator to my project, but
> couldn't figure out how to import it because the documentation didn't
> mention where the validators lives. I had to resort to googling
> "RegexValidator django import" and came across some random pastebin
> which had the import, and then went from there. That wasn't the first
> time I had to do this.
With regards to RegexValidator, the main problem is that
docs/ref/validators.txt does not use the module directive to indicate
which module it is talking about, which is a bug.
If it did, then hovering the mouse over the anchor at the end of each
class/function identifier reveals the import path. (see things like
http://docs.djangoproject.com/en/dev/ref/forms/fields/#django.forms.BooleanField for example). Perhaps this could be more obvious e.g. the module name could also appear at the top of the page.
Also, in the index, the location of each class/function is defined, so
that if you are looking for something specific, you can indeed find
where it lives pretty easily. (Again, it is not correct for
RegexValidator at the moment because of the lack of module directive).
One problem with documentation is that the more unnecessary detail you
add, the harder it becomes to find anything. If you make something too
long people won't bother reading anything at all. The noise of user
added comments on some PHP function pages is unbearable - not that you
were suggesting allowing comments, I'm just saying that excessive
quantity kills usefulness.
I really did not think that your example documentation for slugify added
anything but verbosity to our existing docs. It would not make it easier
to find - our index already lists 'slugify' - and is is mainly a whole
bunch of boilerplate that should be taken for granted by anyone who
understands the basics of Python and the relevant Django subsystem. (And
I don't think we should be aiming at an audience any lower than that in
our docs).
And if you make something 5 times longer but haven't added value, you
have made it a lot worse.
> Right now the documentation consists of a relatively small number of
> pages that are sometimes 50 or 60 screens long (obviously depending on
> screen resolution). What I think it better is to have a much larger
> number of pages, each only being 10 screens long max. One page for
> each model field, one page for each widget type, one page for each
> template tag, etc. Then each page can link to the corresponding
> "topical" documentation page to see how that function/class/object
> relates to the big picture.
The problem is that most model fields are very similar, and have common
options. So splitting up fields into separate pages makes it harder to
find the common options, or means you will end up duplicating a whole
bunch of information pointlessly.
I'm not against changing things in specific cases, but I'm not keen on
the principles behind these changes. Having long pages is not a problem
if you've got a fine-grained table of contents and index which will take
you right to the relevant place - which we do already, and large pages
that collate, for example, all the different fields really help when you
don't know exactly what you want, but you're sure you will find
something useful in the current module.
Finally, some things do not have documentation regarding their import
paths because they are not considered public. Even slugify is only
'public' as a template filter, and for that purpose it is a builtin and
does not need to be imported. We currently make no guarantee that "from
django.template.defaultfilters import slugify" will work in future
AFAIK, or that it will be suitable for use outside the template system.
(It already has some things, related to auto-escaping, that might make
it behave 'funny' depending on what exactly you pass it). I think that
a developer wanting to find function that are not publicly documented
*is* expected to know how to use grep (or 'ack', which is a great
replacement, BTW).
Regards,
Luke
Regards,
Luke
--
"Underachievement: The tallest blade of grass is the first to be
cut by the lawnmower." (despair.com)
Luke Plant || http://lukeplant.me.uk/
dffdgsdfgsdfhjhtre
> Unlike PHP, we have namespaces, which means that providing a list of
> every function/class is a different matter.
fairly well regarded. The one thing that matplotlib doesn't do well is
the topical stuff which django does do well.
> Also, in the index, the location of each class/function is defined, so
> that if you are looking for something specific, you can indeed find
> where it lives pretty easily. (Again, it is not correct for
> RegexValidator at the moment because of the lack of module directive).
documentation....
> One problem with documentation is that the more unnecessary detail you
> add, the harder it becomes to find anything.
> If you make something too
> long people won't bother reading anything at all.
documentation pages need to be split up.
> The noise of user
> added comments on some PHP function pages is unbearable - not that you
> were suggesting allowing comments, I'm just saying that excessive
> quantity kills usefulness.
put it
at the bottom of the page, so it has never bothered me, but if they
were to
remove the blatantly wrong posts it would be a lot more helpful.
> I really did not think that your example documentation for slugify added
> anything but verbosity to our existing docs. It would not make it easier
> to find - our index already lists 'slugify' - and is is mainly a whole
> bunch of boilerplate that should be taken for granted by anyone who
> understands the basics of Python and the relevant Django subsystem.
Other
functions could make use of the "input" and "output" sections more
correctly,
for instance. I only added them to demonstrate what I was aiming at.
Also, another great thing about PHP's documentation is that each and
every
function page is structured the exact same way. You may call it
'boilerplate',
but I call it 'consistent structure'. With PHP's documentation, If you
know
exactly what you're looking for, you can find it very quickly. For
instance
if you want to look up the order of parameters the preg_replace
function takes,
you type "preg_replace" into the search box, then move your eyes down
to the
first pink box. That takes 2 seconds max. For django, if you wanted to
know
the order of parameters the reverse() function takes, it will take you
much
longer. Not _too_ much longer, but
> (And
> I don't think we should be aiming at an audience any lower than that in
> our docs).
>
> And if you make something 5 times longer but haven't added value, you
> have made it a lot worse.
we reorganize what we already have into two supersections; reference,
and topical, since they are aimed at separate audiences and serve
different purposes.
>
> The problem is that most model fields are very similar, and have common
> options. So splitting up fields into separate pages makes it harder to
> find the common options, or means you will end up duplicating a whole
> bunch of information pointlessly.
parameters,
then link to them from each model field's page.
> I'm not against changing things in specific cases, but I'm not keen on
> the principles behind these changes. Having long pages is not a problem
> if you've got a fine-grained table of contents and index which will take
> you right to the relevant place - which we do already, and large pages
> that collate, for example, all the different fields really help when you
> don't know exactly what you want, but you're sure you will find
> something useful in the current module.
>
> Finally, some things do not have documentation regarding their import
> paths because they are not considered public. Even slugify is only
> 'public' as a template filter, and for that purpose it is a builtin and
> does not need to be imported. We currently make no guarantee that "from
> django.template.defaultfilters import slugify" will work in future
> AFAIK, or that it will be suitable for use outside the template system.
> (It already has some things, related to auto-escaping, that might make
> it behave 'funny' depending on what exactly you pass it).
people out
there who use slugify and other template functions outside templates.
I don't
thionk theres anything wrong with encouraging people to do this as
long as you
make it clear that these functions can move and that there may be side
effects
from auto-escaping and such.
Peter2108
the Django code to fill out gaps in the documentation. I think this is
fine: "use the sourse, Luke" has always been a Python thing. But it
would be nice if developers could describe each parameter to the
function/method. This description should include the type of object(s)
the parameter is bound to.
Cheers,
Peter
Luke Plant
> On Jul 4, 8:40 pm, Luke Plant <L.Plant...@cantab.net> wrote:
> > Unlike PHP, we have namespaces, which means that providing a list of
> > every function/class is a different matter.
>
> So? Matplotlib has similar documentation to PHP's reference, and it's
> fairly well regarded. The one thing that matplotlib doesn't do well is
> the topical stuff which django does do well.
Namespaces mean that the same name can refer to different things - like
'Field', all the different 'utils' modules etc. So you can't have a
shortcut that finds a single thing unless you also know which module it
belongs to, but that seemed to be the major problem you were
highlighting.
> > Also, in the index, the location of each class/function is defined, so
> > that if you are looking for something specific, you can indeed find
> > where it lives pretty easily. (Again, it is not correct for
> > RegexValidator at the moment because of the lack of module directive).
>
> I did not know this... Maybe we should have documentation for the
> documentation....
Well, the front page says this in a box right at the top:
Looking for specific information? Try the Index, Module Index or the
detailed table of contents.
and it's the Index you need in this case.
> Also, another great thing about PHP's documentation is that each and
> every function page is structured the exact same way. You may call it
> 'boilerplate', but I call it 'consistent structure'. With PHP's
> documentation, If you know exactly what you're looking for, you can
> find it very quickly. For instance if you want to look up the order
> of parameters the preg_replace function takes, you type "preg_replace"
> into the search box, then move your eyes down to the first pink box.
> That takes 2 seconds max. For django, if you wanted to know the order
> of parameters the reverse() function takes, it will take you much
> longer.
That speed is because PHP has no namespaces (and makes little use of
classes). In this case, when you say "reverse" do you mean
django.core.urlresolvers.reverse or django.db.models.QuerySet.reverse?
So in Django there *has* to be at least one extra step. Equivalent in
Django docs:
1) type 'reverse' in the search box. Click on first hit, look at
'Contents' pane down the right, click 'reverse'.
2) Go to the General Index, click 'R', scroll to 'reverse' and choose
the one you want. (or, go to General Index and use your browser search
functionality e.g. type /reverse in Firefox.)
I guess what you are really asking for is a search box that returns only
exact matches from the index.
> I'm not saying we should make the documentation longer. I'm proposing
> we reorganize what we already have into two supersections; reference,
> and topical, since they are aimed at separate audiences and serve
> different purposes.
We *already* have this - the Module Index and Index (clearly linked from
the front page) are the reference sections, and most of the rest is
topical, with links to the reference sections thrown in.
> > Finally, some things do not have documentation regarding their import
> > paths because they are not considered public. Even slugify is only
> > 'public' as a template filter, and for that purpose it is a builtin and
> > does not need to be imported. We currently make no guarantee that "from
> > django.template.defaultfilters import slugify" will work in future
> > AFAIK, or that it will be suitable for use outside the template system.
> > (It already has some things, related to auto-escaping, that might make
> > it behave 'funny' depending on what exactly you pass it).
>
> Then that should all should be documented!
The fact that only documented functions are considered public *is*
documented: http://docs.djangoproject.com/en/dev/misc/api-stability/
(This is part of the meta-documentation section)
But the details of how the slugify function works should *not* be
documented. It is a *private* implementation detail (at the moment at
least). People who want to use it do so at their own risk, and should
read the source. If you want to propose that these functions be
considered public *as functions*, that is another matter. There are
always various things that ought to become public if they are
sufficiently useful outside of Django internals.
I don't happen to think django.template.defaultfilters is in that
category as it stands - the way those functions work is full of things
that are very specific to the template system.
> There has to be lots of people out there who use slugify and other
> template functions outside templates. I don't thionk theres anything
> wrong with encouraging people to do this as long as you make it clear
> that these functions can move and that there may be side effects
> from auto-escaping and such.
But the point of the internal implementation details is that they can
*change* - if we say "You can use these provided you are aware of points
1), 2) + 3)", we now have to *keep* points 1), 2) and 3), and we can't
add points 4), 5) and 6). Without clairvoyance it is impossible to add
the caveats that we need to add. And we already have the
meta-documentation that says that only publicly documented code is
considered stable (and programmers should in general be able to infer
this anyway).
Regards,
Luke
--
"We may not return the affection of those who like us, but we
always respect their good judgement." -- Libbie Fudim
Luke Plant || http://lukeplant.me.uk/
Ramiro Morales
> There are two types of documentation, "reference" documentation
> (articles explaining all about one specific object such as slugify or
> the Feed class), and "topical" documentation (articles explaining how
> to do stuff like write templates).
It is surprising how what you propose in line with something was already
discussed a couple of years ago and has been the general guideline
in the documentation front work since then:
http://groups.google.com/group/django-developers/browse_thread/thread/dcfaa00df58b6d3b
As Luke says, what is still missing is to complete the addition/separation
of reference material using the tools Sphinx give us, ideally reaching
100% of the
public API reference. This is also documented in a TODO list:
http://docs.djangoproject.com/en/1.2/internals/documentation/#todo
(that would be the "documentation documentation" document you
talk about)
I'd suggest to go forward with you showcasing idea, choose one module that
currently has no reference material, apply the strategy and share your results
with this list.
Regards,
--
Ramiro Morales | http://rmorales.net