should we include images in Django documentation?

[Pieter Marres]

Hi,
Django documentation is an excellent resource but it is mostly text based.
In some occasions, a picture tells more than a 1000 words.
What's your opinion on including some images in the Django documentation?
Pieter

[Aymeric Augustin]

There’s already a few images and I can’t see any reason against adding more
where appropriate.

There’s just one small hurdle. Last time I checked, the intersection of “editors
producing good-looking diagrams” and “open-source diagram editors” was
empty. And we don’t want ASCII diagrams.

For a few years we had some diagrams created with OmniGraffle and rendered
as PNG. When I switched images to vector formats, no one had the source. I
recreated all diagrams and committed the source files. They’ll only be useful to
people who own an OmniGraffle license, but that’s better than nothing.

I would recommend to use a tool that produces good looking results and
commit:
- the source file (in your tool’s default format)
- a SVG export (for the HTML version of the docs)
- a PDF export (for the PDF version of the docs)

I hope this helps.

--
Aymeric.

[Chris Wilson]

Hi all,

On Sat, 22 Feb 2014, Aymeric Augustin wrote:

> There's already a few images and I can't see any reason against adding
> more where appropriate.
>
> There's just one small hurdle. Last time I checked, the intersection of
> "editors producing good-looking diagrams" and "open-source diagram
> editors" was empty. And we don't want ASCII diagrams.

I'm not sure what kind of diagrams we'd be looking for, but I've created
some diagrams with OpenOffice Draw that I'm quite happy with:

https://raw.github.com/aptivate/inaspmaterials/master/src/Network_Management/Unit_5_The_Bandwidth_Challenge/images/congestion-queueing.png
https://raw.github.com/aptivate/inaspmaterials/master/src/Network_Management/Unit_6_Solving_Network_Problems/images/total-bandwidth-illustration.png
https://raw.github.com/aptivate/inaspmaterials/master/src/Network_Management/Unit_11_Technical_Measures/images/hfsc-queueing.png

All of these have .ODG sources in the same directory.

> I would recommend to use a tool that produces good looking results and
> commit:
>
> - the source file (in your tool's default format)
> - a SVG export (for the HTML version of the docs)
> - a PDF export (for the PDF version of the docs)

OpenOffice Draw does export to SVG and PDF. We might also want a .PNG
fallback for browsers that don't support SVG (well).

Cheers, Chris.
--
Aptivate | http://www.aptivate.org | Phone: +44 1223 967 838
Citylife House, Sturton Street, Cambridge, CB1 2QF, UK

Aptivate is a not-for-profit company registered in England and Wales
with company number 04980791.

[Aymeric Augustin]

On 22 févr. 2014, at 20:00, Chris Wilson <ch...@aptivate.org> wrote:

> We might also want a .PNG fallback for browsers that don't support SVG (well).

I haven’t attempted to do that because I don’t think many readers of the Django
documentation use IE8 or earlier for browsing. I haven’t heard anyone complain.

--
Aymeric.