Re: Consensus about visual diagrams in the docs.

[Jani Tiainen]

Personally I use plantuml to generate various diagrams. It is open source
there even exists plugin for sphinx. It uses relatively understandable
diagram language. Exports svg along the many other formats. And there are
realtime preview plugins to most editors and ides.

Only big downside is that requires java runtime.

Curtis Maloney  kirjoitti pe 30. marrask. 2018 klo
21.47:

> On 11/30/18 7:38 PM, guettli wrote:
> > I do not care for the strategy, I care for the goal.
> >
> > How to find clear consensus now?
>
> There is a time honored practice in open source of spurring more
> spirited discussion by presenting a solution, however sub-optimal it may
> be.
>
> It may not be the accepted solution, but it's far more likely to get
> people to give input than asking for discussion.
>
> [No, I'm not just wrapping up "patches welcome" - this is a general
> observation in life. It's just more openly recognised in OSS :) ]
>
> --
> Curtis
>
> --
> You received this message because you are subscribed to the Google Groups
> "Django developers  (Contributions to Django itself)" group.
> To unsubscribe from this group and stop receiving emails from it, send an
> email to django-developers+unsubscr...@googlegroups.com.
> To post to this group, send email to django-developers@googlegroups.com.
> Visit this group at https://groups.google.com/group/django-developers.
> To view this discussion on the web visit
> https://groups.google.com/d/msgid/django-developers/88fbd91d-e4ee-89ac-5bae-1c54f7560698%40tinbrain.net
> .
> For more options, visit https://groups.google.com/d/optout.
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/CAHn91ofesmCYF8dF81KGqL4SRgrHyCRyiWO-2mB%3Dc6HW-Q%3Dysg%40mail.gmail.com.
For more options, visit https://groups.google.com/d/optout.

Re: Consensus about visual diagrams in the docs.

[Curtis Maloney]

On 11/30/18 7:38 PM, guettli wrote:

I do not care for the strategy, I care for the goal.

How to find clear consensus now?


There is a time honored practice in open source of spurring more 
spirited discussion by presenting a solution, however sub-optimal it may be.


It may not be the accepted solution, but it's far more likely to get 
people to give input than asking for discussion.


[No, I'm not just wrapping up "patches welcome" - this is a general 
observation in life. It's just more openly recognised in OSS :) ]


--
Curtis

--
You received this message because you are subscribed to the Google Groups "Django 
developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/88fbd91d-e4ee-89ac-5bae-1c54f7560698%40tinbrain.net.
For more options, visit https://groups.google.com/d/optout.

Re: Consensus about visual diagrams in the docs.

[Aymeric Augustin]

Hello,

A few years ago, I redid most illustrations and included them in the docs as 
SVG files. The primary driver was switching from PNG to SVG to better 
accommodate hi-dpi displays. I also committed the source files. Unfortunately, 
they're in a proprietary format and cannot be reused without a Mac and an 
OmniGraffle licence.

(Before someone starts listing the arguments against proprietary formats — yes, 
I learnt them 15 years ago, and yes, I still chose OmniGraffle's UX over 
Inkscape's. : You're welcome to redo the diagrams with Inkscape and replace 
mine as long as the result doesn't look significantly worse.)

While not ideal, this got the job done. Diagrams look all right on all kind of 
devices.

To sum up:
- I think SVG should be the preferred format for illustrations in the docs
- I'm worried about ASCII art on small devices: line wrapping would be a problem
- whatever you want to make the diagram as long as it exports to SVG and looks 
reasonable
- commit the source file so someone has a chance to reuse them, regardless of 
their format

Best regards,

-- 
Aymeric.



> On 30 Nov 2018, at 09:38, guettli  wrote:
> 
> I once created a simple ascii diagram to explain details of the Django ORM:
> 
> https://code.djangoproject.com/ticket/27936
> 
> Years ago it took some time for me to understand it. And since then it
> came up by new comers in our team several times.
> 
> There is agreement on the goal: yes, a visual diagrams in the docs would be 
> nice.
> 
> But there is no agreement on the strategy.
> 
> I think ascii art is fine. Some suggest to use a graphiz plugin in for sphinx.
> 
> There is no progress because there is no clear consensus up to now.
> 
> I do not care for the strategy, I care for the goal.
> 
> How to find clear consensus now?
> 
> Regards,
>Thomas Güttler
> 
> -- 
> You received this message because you are subscribed to the Google Groups 
> "Django developers (Contributions to Django itself)" group.
> To unsubscribe from this group and stop receiving emails from it, send an 
> email to django-developers+unsubscr...@googlegroups.com 
> .
> To post to this group, send email to django-developers@googlegroups.com 
> .
> Visit this group at https://groups.google.com/group/django-developers 
> .
> To view this discussion on the web visit 
> https://groups.google.com/d/msgid/django-developers/2f6f3c4e-44cf-4b35-bb09-751828cc4921%40googlegroups.com
>  
> .
> For more options, visit https://groups.google.com/d/optout 
> .

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/D58AA4E7-AC5B-425E-BC70-A63C3D11FC87%40polytechnique.org.
For more options, visit https://groups.google.com/d/optout.

Consensus about visual diagrams in the docs.

[guettli]

I once created a simple ascii diagram to explain details of the Django ORM:

https://code.djangoproject.com/ticket/27936

Years ago it took some time for me to understand it. And since then it
came up by new comers in our team several times.

There is agreement on the goal: yes, a visual diagrams in the docs would be 
nice.

But there is no agreement on the strategy.

I think ascii art is fine. Some suggest to use a graphiz plugin in for 
sphinx.

There is no progress because there is no clear consensus up to now.

I do not care for the strategy, I care for the goal.

How to find clear consensus now?

Regards,
   Thomas Güttler

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To post to this group, send email to django-developers@googlegroups.com.
Visit this group at https://groups.google.com/group/django-developers.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/2f6f3c4e-44cf-4b35-bb09-751828cc4921%40googlegroups.com.
For more options, visit https://groups.google.com/d/optout.