Re: Diagrams


Richard Purdie
 

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

Join yocto@lists.yoctoproject.org to automatically receive all group messages.