Diagrams

Diagrams

[Rifenbark, Scott M]

[-- Attachment #1: Type: text/plain, Size: 1094 bytes --]

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.

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?

Scott Rifenbark
Intel Corporation
Yocto Project Documentation
503.712.2702
503.341.0418 (cell)


[-- Attachment #2: Type: text/html, Size: 6737 bytes --]

Re: Diagrams

[Joshua Lock]

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

Re: 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@yoctoproject.org [mailto:yocto-bounces@yoctoproject.org] On Behalf Of Joshua Lock
Sent: Friday, May 13, 2011 2:45 PM
To: yocto@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@yoctoproject.org
https://lists.yoctoproject.org/listinfo/yocto

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