[yocto] Diagrams

[Rifenbark, Scott M]

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...

-----Original Message-----
From: yocto-bounces at yoctoproject.org [mailto:yocto-bounces at yoctoproject.org] On Behalf Of Joshua Lock
Sent: Friday, May 13, 2011 2:45 PM
To: yocto at yoctoproject.org
Subject: Re: [yocto] Diagrams

On Fri, 2011-05-13 at 14:07 -0700, Rifenbark, Scott M wrote:
> Currently I have been consistently using a ‘figures’ directory within
> each manual directory to house any PNG files used in a given manual.
> However, the Yocto-docs repository has a ‘diagrams’ folder at the same
> level as ‘documentation’.  I think we should continue to keep figures
> with their respective books and not in some higher-level folder at the
> same level of documentation.
> 

The benefit of the "store them all in the same folder" approach is that
I can easily find and view the diagrams which might be useful without
having to dig through several folders. I can of course understand the
alternative argument you make.

>  
> 
> This brings up some questions.  Let’s say you have a figure that is
> somewhat universal and is used often by the community, such as this
> ‘oearch.png’ figure.  But, the figure is also part of a manual.  Do we
> keep the figure in the manual’s ‘figures’ folder exclusively?  Or,
> duplicate the figure and keep it in the higher-level ‘diagrams’ folder
> as well?
> 
>  
> 
> It goes against good practice to duplicate things so I would lean
> toward keeping the figures with the documents.  And, if we have
> figures that are not used in any documentation we could keep them in
> the higher-level ‘diagrams’ folder. 
> 
>  
> 
> Thoughts?
> 

I completely agree with the duplication point. I think git should handle
symlinks pretty well so we could store them all in the central directory
and link to the documentation sub-folders, or vice-versa?

Cheers,
Joshua
-- 
Joshua Lock
        Yocto Build System Monkey
        Intel Open Source Technology Centre

_______________________________________________
yocto mailing list
yocto at yoctoproject.org
https://lists.yoctoproject.org/listinfo/yocto