Re: Questions about documentation management

[Aryeh Leib Taurog]

I forgot to mention: Python itself, as of 2.6 I believe, uses Sphinx

http://docs.python.org/release/2.6/documenting/index.html

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

Re: Questions about documentation management

[Russell Keith-Magee]

On Tue, Feb 8, 2011 at 5:50 AM, Aryeh Leib Taurog  wrote:
> On Feb 7, 10:29 pm, anastasia  wrote:
>
> Disclaimer: I'm not really responsible for django documentation, but
> have poked at it a bit, and am somewhat familiar with the platforms.

For the record, I *am* responsible for Django's documentation, and
most of the answers provided by Aryeh are correct. A couple of minor
clarifications:

>> - What did you like about your platform? What are its weaknesses?
>
> * growing in popularity and is used by many projects (See 
> http://readthedocs.org/)
> * python based
> * can output many different formats including html, windows chm, latex/
> pdf

I would also add: Easily writable and readable by humans without
extensive tool support. It's a very lightweight markup format, and the
source is almost as readable as the final product.

>> - Do you use any form of auto-generated API documentation? If so, how
>> to you manage integration with more narrative text such as tutorials,
>> examples, etc?
>
> I don't believe that django does, but sphinx is capable of this.
> See the matplotlib documentation, for example.  I believe the api docs
> are auto-generated.
>
> http://matplotlib.sourceforge.net/api/index.html

Django doesn't have autogenerated API docs -- mostly (IMHO) because
this is a feature of Python itself -- anything that could be
automatically generated could also be determined using the interactive
prompt.

>> - Are developers involved in writing the documentation, or is that
>> left to technical writers?
>
> Seems to me the developers do it.

Correct, although:

 * We have a couple of committers whose sole responsibility is to
maintain the documentation

 * Several of our core committers, including our two BDFLs have formal
training in the arts; Adrian is a Journalism major, and Jacob is an
American Literature major. We also have a Philosophy major and three
doctorates in our team. Overall, the "developers" are a literate
bunch, not just a bunch of hackers forced to write some docs.

>> - Do you support community input/editing of documentation? Why or why
>> not?
>
> Seems to me that documentation is treated same as code.  Those who
> have commit rights commit; the rest of us submit patches.

Correct -- as for the reasoning behind this: our experience has been
that wikis become a wasteland. Good documentation, like good design,
isn't something that can be arrived at by committee, or by consensus
-- it requires strong decision making and editorial 'taste' to build a
coherent and useful body of documentation.

However, we are exploring some ways to make it easier for people to
contribute suggestions and modifications to the documentation.

Yours,
Russ Magee %-)

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

Re: Questions about documentation management

[Aryeh Leib Taurog]

On Feb 7, 10:29 pm, anastasia  wrote:

Disclaimer: I'm not really responsible for django documentation, but
have poked at it a bit, and am somewhat familiar with the platforms.

> - What platform does Django use for its documentation? (e.g. a wiki?
> DocBook?)

Sphinx
http://sphinx.pocoo.org/

Based on reStructured text, a very extensible lightweight markup
http://docutils.sourceforge.net/rst.html

> - What did you like about your platform? What are its weaknesses?

* growing in popularity and is used by many projects (See 
http://readthedocs.org/)
* python based
* can output many different formats including html, windows chm, latex/
pdf

> - How easy or hard it is to customize the look and feel of the
> interface with your platform? i.e. style, layout, navigation, etc.

relatively easy

> - Do you use any form of auto-generated API documentation? If so, how
> to you manage integration with more narrative text such as tutorials,
> examples, etc?

I don't believe that django does, but sphinx is capable of this.
See the matplotlib documentation, for example.  I believe the api docs
are auto-generated.

http://matplotlib.sourceforge.net/api/index.html

> - How do you manage versioning of your documentation (i.e.
> documentation specific to a particular version of Processing)?

Since the source is plain text, they are kept in django svn

> - Are developers involved in writing the documentation, or is that
> left to technical writers?

Seems to me the developers do it.

> - Do you support community input/editing of documentation? Why or why
> not?

Seems to me that documentation is treated same as code.  Those who
have commit rights commit; the rest of us submit patches.

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

Questions about documentation management

[anastasia]

Hello,

My name is Anastasia Cheetham. I'm a developer with and the
documentation lead for the Fluid Project (http://fluidproject.org).
We're beginning the process of restructuring and redesigning the
documentation for our Infusion framework. Part of that process will
include migrating to a new platform for the creation and distribution
of documentation, and we're interested in learning about the
experiences of other open source projects, including Django. I'm
hoping that someone might have time to share some thoughts about how
you team manages documentation. For example:

- What platform does Django use for its documentation? (e.g. a wiki?
DocBook?)

- What did you like about your platform? What are its weaknesses?

- How easy or hard it is to customize the look and feel of the
interface with your platform? i.e. style, layout, navigation, etc.

- Do you use any form of auto-generated API documentation? If so, how
to you manage integration with more narrative text such as tutorials,
examples, etc?

- How do you manage versioning of your documentation (i.e.
documentation specific to a particular version of Processing)?

- Are developers involved in writing the documentation, or is that
left to technical writers?

- Do you support community input/editing of documentation? Why or why
not?


I thank you very much for your time, and for any thoughts you can
share.

--
Anastasia Cheetham Inclusive Design Research Centre
acheet...@ocad.caInclusive Design Institute
   OCAD University

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