Re: Diagrams

[Richard Purdie <richard.purdie@linuxfoundation.org>]

Hi Scott,

On Fri, 2011-05-13 at 14:59 -0700, Rifenbark, Scott M wrote:
> One thing that happens when you keep all figures in a folder that is 
> hierarchically level with 'documentation' is that the figures become 
> separated from the 'documentation' leg so to speak. It use to be that
> good file organization practice for manuals was to keep all parts of a
> manual together.  But, as single-sourcing becomes more popular along
> with 'chunking' of information, that practice isn't as rigid.  
> 
> If we kept all diagrams in a single 'diagram' folder I would like to
> see it at least under the 'documentation' folder.  Then we could
> organize the 'diagram' folder into source files and rendered (PNG or
> SVG) files.  Using a single diagram directory will also cause the
> Makefiles to be re-worked for pushing files to the web-site.
> Additionally, the directory structure in the Drupal site for
> yoctoproject.org would need to be re-structured to look for PNG files
> in the new location.  
> 
> I see benefits and problems in all methods...

I thought I'd cc'd you on some other email where we talked about
starting to store some of the other material we have about yocto
alongside the documentation in the yocto-docs repository.

By this I'm thinking of presentations, graphics, diagrams and other
technical content as at the moment we all have to rummage around a lot
of separate locations whenever we want to pull a presentation together.

The hierarchy of the information needs to be designed but we have to
following needs:

a) Has a folder which contains the subset of information we integrate 
   into the poky repository and ship with the build system and 
   metadata. The development manuals and quick start are obviously 
   requirements there and the current documentation directory fits this
   well. If we want to rename it, so be it but I don't think its 
   function has changed.

b) Can store other kinds of material (presentations, diagrams, 
   graphics) meeting out immediate needs.

c) Is extensible to meet future requirements we don't yet know about.

This separate also makes some sense when you consider what we push to
the website. The reference manuals certainly make sense, I'm not sure
that the presentations or diagrams would make sense in their own rights
though.

I agree splitting by source and rendered versions makes sense. I'd not
confuse the fact that the manuals include some of these diagrams with
the fact that we need to store the source of the diagrams (and some
pre-rendered sample output of them) somewhere though. The manuals are a
pure consumer of them, likewise presentations including them and so
forth.

Cheers,

Richard