Documentation Hackathon

[Ron Wheeler <rw...@artifact-software.com>]

While discussing the documentation, issues were raised about the 
diagrams in the documentation.

1) It was felt that some of the diagrams looked a bit old fashioned

2) The sources for images seemed to be lost or held outside the SCM.

This encouraged me to look at ways to improve the production of images 
for the documentation.

I had the following as goals:

a) The tools used should be open source so everyone can use the same 
sources.

b) The tools should not require specialized expertise to use.

c) It must be possible to produce images that can be used in other tools 
(Confluence Wiki includes drawing tools but there is no way to use the 
images outside confluence).

d) There should be a library of relevant images.

At the meeting Visio and Apache OpenOffice Draw were mentioned as 
possible drawing tools. Visio is an excellent product but is proprietary.

Apache OpenOffice Draw is an Apache product and very well supported.

After a bit of research I found a library of OpenOffice symbols from VRT 
(http://www.vrt.com.au/downloads/vrt-network-equipment) that seems to 
include many of the symbols that we need.

I tested the addition of the library into OpenOffice using the normal 
add-on process and it works well.

Requires a restart of Open Office after the update but that is to be 
expected.

I used it to create an equivalent diagram for one of the drawings from 
the current doc set.

You can see the results and a short discussion at 
http://blog.artifact-software.com/tech/?p=305

The OpenOffice Draw source can be downloaded from the article to see how 
the png files where created.

It is possible to produce many output formats beside png from OpenOffice.


Ron


-- 
Ron Wheeler
President
Artifact Software Inc
email: rwheeler@artifact-software.com
skype: ronaldmwheeler
phone: 866-970-2435, ext 102

Re: Documentation Hackathon

[Dag Sonstebo <Da...@shapeblue.com>]

Hi Ron,

great to catch up in Montreal, good session and I think we are on the right path going forward. Thanks for looking into the diagram generation, very useful and something we should look at when we start revising the content.

For everyone's benefit - we are kicking off a piece of work to first of all consolidate all documentation under one document tree, as well as improving overview and navigation. We are also considering what the best framework is for hosting the consolidated documents going forward. I'll make sure we have tracking list of where we are with each section either on the wiki or on github in the coming days.

Regards,
Dag Sonstebo






On 06/06/2016, 02:49, "Ron Wheeler" <rw...@artifact-software.com> wrote:

>While discussing the documentation, issues were raised about the 
>diagrams in the documentation.
>
>1) It was felt that some of the diagrams looked a bit old fashioned
>
>2) The sources for images seemed to be lost or held outside the SCM.
>
>This encouraged me to look at ways to improve the production of images 
>for the documentation.
>
>I had the following as goals:
>
>a) The tools used should be open source so everyone can use the same 
>sources.
>
>b) The tools should not require specialized expertise to use.
>
>c) It must be possible to produce images that can be used in other tools 
>(Confluence Wiki includes drawing tools but there is no way to use the 
>images outside confluence).
>
>d) There should be a library of relevant images.
>
>At the meeting Visio and Apache OpenOffice Draw were mentioned as 
>possible drawing tools. Visio is an excellent product but is proprietary.
>
>Apache OpenOffice Draw is an Apache product and very well supported.
>
>After a bit of research I found a library of OpenOffice symbols from VRT 
>(http://www.vrt.com.au/downloads/vrt-network-equipment) that seems to 
>include many of the symbols that we need.
>
>I tested the addition of the library into OpenOffice using the normal 
>add-on process and it works well.
>
>Requires a restart of Open Office after the update but that is to be 
>expected.
>
>I used it to create an equivalent diagram for one of the drawings from 
>the current doc set.
>
>You can see the results and a short discussion at 
>http://blog.artifact-software.com/tech/?p=305
>
>The OpenOffice Draw source can be downloaded from the article to see how 
>the png files where created.
>
>It is possible to produce many output formats beside png from OpenOffice.
>
>
>Ron
>
>
>-- 
>Ron Wheeler
>President
>Artifact Software Inc
>email: rwheeler@artifact-software.com
>skype: ronaldmwheeler
>phone: 866-970-2435, ext 102
>

Dag.Sonstebo@shapeblue.com 
www.shapeblue.com
53 Chandos Place, Covent Garden, London  WC2N 4HSUK
@shapeblue