Re: A project we can learn from

On 11/11/2009, at 12:43 PM, JoAnna Springsteen wrote:

> Saw this article posted on twitter and wanted to point it out to the  
> doc team:
>
> http://jacobian.org/writing/good-documentation/
>
> Django has some *awesome* docs. We could really learn a lot from their
> docs but also their "documentation culture", as the author refers to
> it.
> This looks like just the first in a series of posts. I'm interested in
> what other advice and tips we can borrow from this. Django really is a
> project we can learn a lot from in regards to making our entire doc
> set the best it can be.


some great stuff in there.

I especially like

"While it’s true that books shine in the “topical guide” area, they’re  
not really a great substitute for guides as part of the official  
documentation. Official docs, even when done poorly, are usually much  
more up-to-date; books, even when done well, are often out of date the  
day they hit the shelves"

and the fact that you WILL need all three kinds of documentation

"Tech docs can take a bunch of different forms ranging from high-level  
overviews, to step-by-step walkthroughs, to auto-generated  
APIdocumentation. Unfortunately, no single format works for all users;  
there’s huge differences in the way that people learn, so a well- 
documented project needs to provide many different forms of  
documentation.
"

With regard to the developer manual, whats the procedure for ripping  
out topical overviews like those of Martins and putting them into an  
aggregated manual that will be maintained by everyone? Is it just a  
matter of asking the authors permission?


>
> Happy reading!
>
> JoAnna
>
> ------------------------------------------------------------------------------
> Let Crystal Reports handle the reporting - Free Crystal Reports 2008  
> 30-Day
> trial. Simplify your report design, integration and deployment - and  
> focus on
> what you do best, core application coding. Discover what's new with
> Crystal Reports now.  http://p.sf.net/sfu/bobj-july
> _______________________________________________
> Plone-docs mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/plone-docs


------------------------------------------------------------------------------
Let Crystal Reports handle the reporting - Free Crystal Reports 2008 30-Day 
trial. Simplify your report design, integration and deployment - and focus on 
what you do best, core application coding. Discover what's new with
Crystal Reports now.  http://p.sf.net/sfu/bobj-july