<p dir="ltr">In ironic, we have use asciiflow several times quite successfully in the spec process.</p>
<p dir="ltr">We also maintain in-tree docs with .PNG graphics, and versioning those has been a bit of a pain. They were originally taken out of slide decks, and served their purpose, but really ought to be in a different format or a different tree now.</p>
<p dir="ltr">-D</p>
<div class="gmail_quote">On May 12, 2015 2:15 AM, "John Garbutt" <<a href="mailto:john@johngarbutt.com">john@johngarbutt.com</a>> wrote:<br type="attribution"><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">On 11 May 2015 at 23:46, Boris Pavlovic <<a href="mailto:boris@pavlovic.me">boris@pavlovic.me</a>> wrote:<br>
>> Couldn't we just use real image files to do this. IIRC, gerrit supports<br>
>> displaying image files which are included in a commit. For example, I've<br>
>> been<br>
>> planning to copy these images:<br>
><br>
> +1 for real images<br>
<br>
One suggestion I remember around specs was we might want a separate<br>
repo to contain the images, to stop massively increasing the git clone<br>
times.<br>
<br>
In the spec template we recommend this to generate diagrams:<br>
<a href="http://asciiflow.com/" target="_blank">http://asciiflow.com/</a><br>
<br>
See:<br>
<a href="http://specs.openstack.org/openstack/nova-specs/specs/liberty/template.html" target="_blank">http://specs.openstack.org/openstack/nova-specs/specs/liberty/template.html</a><br>
<br>
Thanks,<br>
John<br>
<br>
> On Tue, May 12, 2015 at 1:36 AM, Matthew Treinish <<a href="mailto:mtreinish@kortar.org">mtreinish@kortar.org</a>><br>
> wrote:<br>
>><br>
>> On Mon, May 11, 2015 at 02:57:48PM -0700, Joe Gordon wrote:<br>
>> > When learning about how a project works one of the first things I look<br>
>> > for<br>
>> > is a brief architecture description along with a diagram. For most<br>
>> > OpenStack projects, all I can find is a bunch of random third party<br>
>> > slides<br>
>> > and diagrams.<br>
>> ><br>
>> > Most Individual OpenStack projects have either no architecture diagram<br>
>> > or<br>
>> > ascii art. Searching for 'OpenStack X architecture' where X is any of<br>
>> > the<br>
>> > OpenStack projects turns up pretty sad results. For example heat [0] an<br>
>> > Keystone [1] have no diagram. Nova on the other hand does have a<br>
>> > diagram,<br>
>> > but its ascii art [2]. I don't think ascii art makes for great user<br>
>> > facing<br>
>> > documentation (for any kind of user).<br>
>> ><br>
>> > So how can we do better then ascii art architecture diagrams?<br>
>> ><br>
>> > [0] <a href="http://docs.openstack.org/developer/heat/architecture.html" target="_blank">http://docs.openstack.org/developer/heat/architecture.html</a><br>
>> > [1] <a href="http://docs.openstack.org/developer/keystone/architecture.html" target="_blank">http://docs.openstack.org/developer/keystone/architecture.html</a><br>
>> > [2] <a href="http://docs.openstack.org/developer/nova/devref/architecture.html" target="_blank">http://docs.openstack.org/developer/nova/devref/architecture.html</a><br>
>><br>
>> Couldn't we just use real image files to do this. IIRC, gerrit supports<br>
>> displaying image files which are included in a commit. For example, I've<br>
>> been<br>
>> planning to copy these images:<br>
>><br>
>> <a href="https://wiki.openstack.org/wiki/QA/AuthInterface" target="_blank">https://wiki.openstack.org/wiki/QA/AuthInterface</a><br>
>><br>
>> into the tempest docs for some time. They just need to be updated a bit to<br>
>> reflect some recent changes.<br>
>><br>
>> The only downside I see is that it makes editing more difficult, I guess<br>
>> that's<br>
>> really the tradeoff.<br>
>><br>
>> -Matt Treinish<br>
>><br>
>> __________________________________________________________________________<br>
>> OpenStack Development Mailing List (not for usage questions)<br>
>> Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
>> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
>><br>
><br>
><br>
> __________________________________________________________________________<br>
> OpenStack Development Mailing List (not for usage questions)<br>
> Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
><br>
<br>
__________________________________________________________________________<br>
OpenStack Development Mailing List (not for usage questions)<br>
Unsubscribe: <a href="http://OpenStack-dev-request@lists.openstack.org?subject:unsubscribe" target="_blank">OpenStack-dev-request@lists.openstack.org?subject:unsubscribe</a><br>
<a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev" target="_blank">http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev</a><br>
</blockquote></div>