Radiance documentation organization

I promised at the Leicester workshop to propose a hierarchy for extant Radiance documentation, sort of a straw man to get people thinking about this. I strongly encourage others to rearrange these topics, change names, add categories, etc.

Thinking about it for a bit, I opted for a functional organization over an application-based hierarchy, simply because so many tools and techniques are common to different applications, and I was trying to keep the organization as tree-like as possible, realizing that this goal is basically unachievable.

Caveats aside, here's what I have:

I. Input
  A. CAD links and conversion tools
  B. Photometry & Sky models
  C. Generator programs
  D. Scene processing (xform, replmarks, oconv, etc.)

II. Computation
  A. Rendering (batch & interactive)
  B. Illumination calculations
  C. Executive programs (rad, rayfront, etc.)

III. Output
  A. Image processing
  B. Image viewing
  C. Image format conversion
  D. Graphing & plotting

In addition, I suggest we include an alternate arrangement of tutorial materials, which necessarily bridge these functional boundaries. I am hoping others can offer suggestions for how these should be organized, as I don't even have a good list of tutorials available.

Some thought should also be given to how one might organize materials from the Radiance workshops. Again, the basic categories above will be bridged or extended by many of the talks, and the chronological arrangement we now have is of less and less use as time goes on.

Help, please!
-Greg

Hi Greg

Thinking about it for a bit, I opted for a functional organization over an application-based hierarchy, simply because so many tools and techniques are common to different applications,

I think a functional organization fits the need of the user most, indeed. Applications and tutorials might be added to the end of the list, just for those who want to browse through them, which can be very learnfull for both beginners and experienced users.
Every search in the tree will end in some article. If just each article will end with related tutorials and applications, that in itself is a way of organizing tutorials and applications.

What might be added is an Installation chapter, which covers also different platforms, different shells and additional software developments like radzilla.

I don't know what you exectly have in mind, but as you say : "help, please!", using wikipedia (there already is a small wiki about Radiance software) might be an option to have lots of us working on the same documentation. If those who now are active in this mailinglist spent just some time in writing articles and updating hyperlinks now and then, then over some years a real nice documentation will be just there. Wikipedia also has an option for creating Wiki-books as pdf.

Iebele

···

Caveats aside, here's what I have:

I. Input
    A. CAD links and conversion tools
    B. Photometry & Sky models
    C. Generator programs
    D. Scene processing (xform, replmarks, oconv, etc.)

II. Computation
    A. Rendering (batch & interactive)
    B. Illumination calculations
    C. Executive programs (rad, rayfront, etc.)

III. Output
    A. Image processing
    B. Image viewing
    C. Image format conversion
    D. Graphing & plotting

In addition, I suggest we include an alternate arrangement of tutorial materials, which necessarily bridge these functional boundaries. I am hoping others can offer suggestions for how these should be organized, as I don't even have a good list of tutorials available.

Some thought should also be given to how one might organize materials from the Radiance workshops. Again, the basic categories above will be bridged or extended by many of the talks, and the chronological arrangement we now have is of less and less use as time goes on.

Help, please!
-Greg

_______________________________________________
Radiance-general mailing list
[email protected]
http://www.radiance-online.org/mailman/listinfo/radiance-general

I like Leble's suggestions, particularly using Wikipedia. Wouldn't Wikipedia reduce the burden on individuals? Is there any disadvantage to using Wikipedia?

Take care,

Chris Jessee

···

On Oct 25, 2006, at 10:09 AM, iebele wrote:

Hi Greg

Thinking about it for a bit, I opted for a functional organization over an application-based hierarchy, simply because so many tools and techniques are common to different applications,

I think a functional organization fits the need of the user most, indeed. Applications and tutorials might be added to the end of the list, just for those who want to browse through them, which can be very learnfull for both beginners and experienced users.
Every search in the tree will end in some article. If just each article will end with related tutorials and applications, that in itself is a way of organizing tutorials and applications.

What might be added is an Installation chapter, which covers also different platforms, different shells and additional software developments like radzilla.

I don't know what you exectly have in mind, but as you say : "help, please!", using wikipedia (there already is a small wiki about Radiance software) might be an option to have lots of us working on the same documentation. If those who now are active in this mailinglist spent just some time in writing articles and updating hyperlinks now and then, then over some years a real nice documentation will be just there. Wikipedia also has an option for creating Wiki-books as pdf.

Iebele

Caveats aside, here's what I have:

I. Input
    A. CAD links and conversion tools
    B. Photometry & Sky models
    C. Generator programs
    D. Scene processing (xform, replmarks, oconv, etc.)

II. Computation
    A. Rendering (batch & interactive)
    B. Illumination calculations
    C. Executive programs (rad, rayfront, etc.)

III. Output
    A. Image processing
    B. Image viewing
    C. Image format conversion
    D. Graphing & plotting

In addition, I suggest we include an alternate arrangement of tutorial materials, which necessarily bridge these functional boundaries. I am hoping others can offer suggestions for how these should be organized, as I don't even have a good list of tutorials available.

Some thought should also be given to how one might organize materials from the Radiance workshops. Again, the basic categories above will be bridged or extended by many of the talks, and the chronological arrangement we now have is of less and less use as time goes on.

Help, please!
-Greg

_______________________________________________
Radiance-general mailing list
[email protected]
http://www.radiance-online.org/mailman/listinfo/radiance-general

_______________________________________________
Radiance-general mailing list
[email protected]
http://www.radiance-online.org/mailman/listinfo/radiance-general

Hi Iebele,

Good point about installation. That definitely deserves its own category, which I simply forgot. I've also added a tutorials section, which we may as well break into categories as well:

I. Installation and Set-up
  A. Standard (UNIX) distirbution
  B. Radzilla
  C. Windows alternatives
  D. Other packages

II. Tutorials
  A. Basic
  B. General, Advanced
  B. Electric Lighting
  C. Daylighting

III. Input
  A. CAD links and conversion tools
  B. Photometry & Sky models
  C. Generator programs
  D. Scene processing (xform, replmarks, oconv, etc.)

IV. Computation
  A. Rendering (batch & interactive)
  B. Illumination calculations
  C. Executive programs (rad, rayfront, etc.)

V. Output
  A. Image processing
  B. Image viewing
  C. Image format conversion
  D. Graphing & plotting

Regarding Wikipedia, I think the discussion we had at the workshop was leaning towards a more controlled environment, where people would still be very free to contribute but responsible for particular parts of the documentation tree. This was the plone-based solution that Peter Apian-Bennewitz proposed last year. Much hints on getting some seed (and hopefully ongoing) funding for that.

-Greg

Hi Greg,

I've checked plone. I am not convinced that this will encourage people to work on the documentation. I haven't seen convincing running examples yet - maybe others have ?

Concerning Wikipedia:

Please have a look at http://www.mediawiki.org/wiki/MediaWiki.

This is a free software distribution which requires only MySQL, Apache and PHP to run.

When this wiki software is installed on a server, it /is/ a controlled environment. Most important feature imho is that only registered users can edit articles.

What kind of funding is required ? A webserver ?

-Iebele

···

Hi Iebele,

Good point about installation. That definitely deserves its own category, which I simply forgot. I've also added a tutorials section, which we may as well break into categories as well:

I. Installation and Set-up
    A. Standard (UNIX) distirbution
    B. Radzilla
    C. Windows alternatives
    D. Other packages

II. Tutorials
    A. Basic
    B. General, Advanced
    B. Electric Lighting
    C. Daylighting

III. Input
    A. CAD links and conversion tools
    B. Photometry & Sky models
    C. Generator programs
    D. Scene processing (xform, replmarks, oconv, etc.)

IV. Computation
    A. Rendering (batch & interactive)
    B. Illumination calculations
    C. Executive programs (rad, rayfront, etc.)

V. Output
    A. Image processing
    B. Image viewing
    C. Image format conversion
    D. Graphing & plotting

Regarding Wikipedia, I think the discussion we had at the workshop was leaning towards a more controlled environment, where people would still be very free to contribute but responsible for particular parts of the documentation tree. This was the plone-based solution that Peter Apian-Bennewitz proposed last year. Much hints on getting some seed (and hopefully ongoing) funding for that.

-Greg

_______________________________________________
Radiance-general mailing list
[email protected]
http://www.radiance-online.org/mailman/listinfo/radiance-general

Hi Iebele,

We tried a Wiki for Radiance already and it didn't go anywhere, and was inundated by adware. I don't really blame Wiki for this -- the problem was more lack of groundswell and necessary controls, which I'm sure we could remedy if we were a little more organized.

I am not versed on the merits of or differences between Plone and Wiki, and I know very little about either. Both Peter Apian-Bennewitz and Daniel Fuller (the sysadmin for LBL's website) say Plone is better, but you would have to ask them for details. I'm willing to trust others' judgement on the matter, as I have no expertise in the area of web management. I can make some simple HTML, and that's about it.

The important thing is that we agree to contribute material, and the site administrator should be happy and/or paid for their efforts, which I suspect would be substantial using either system. In other words, setting up a Wiki site may be easy, but protecting it from adware while developing useful content may in fact be easier with Plone. I leave the debate to others.

-Greg

···

From: iebele <[email protected]>
Date: November 2, 2006 11:53:41 PM PST

Hi Greg,

I've checked plone. I am not convinced that this will encourage people to work on the documentation. I haven't seen convincing running examples yet - maybe others have ?

Concerning Wikipedia:

Please have a look at http://www.mediawiki.org/wiki/MediaWiki.

This is a free software distribution which requires only MySQL, Apache and PHP to run.

When this wiki software is installed on a server, it /is/ a controlled environment. Most important feature imho is that only registered users can edit articles.

What kind of funding is required ? A webserver ?

-Iebele

Hello all,

I recently deployed MediaWiki for use at work and the way we set it up was that a) you must be logged in to edit anything and b) certain people or groups of people we're placed in charge of different sections on the Wiki, meaning that they were the only ones who could directly contribute to that particular page (individual users can protect pages with a separate password that will allow only them to edit it). However, we also set up a "drafts" page which was linked from the main page that was essentially a mirror of each page. Anyone logged in could edit and add to this draft page and every once in awhile the person(s) in charge of the section will go through the draft and add things that are relevant and correct to the main page. This helps us make sure that there is limited spamming (and NO spamming on the main pages) and it helps us ensure the accuracy and helpfulness of items within the wiki. I'm not familiar with Plone, but I would imagine a similar setup could be arranged with that as well.

Granted, this does not solve the issue of actually convincing people to contribute to such a setup, but something like this would help significantly with quality control and making sure that little or no spam makes its way to the wiki.

Dave

Gregory J. Ward wrote:

···

Hi Iebele,

We tried a Wiki for Radiance already and it didn't go anywhere, and was inundated by adware. I don't really blame Wiki for this -- the problem was more lack of groundswell and necessary controls, which I'm sure we could remedy if we were a little more organized.

I am not versed on the merits of or differences between Plone and Wiki, and I know very little about either. Both Peter Apian-Bennewitz and Daniel Fuller (the sysadmin for LBL's website) say Plone is better, but you would have to ask them for details. I'm willing to trust others' judgement on the matter, as I have no expertise in the area of web management. I can make some simple HTML, and that's about it.

The important thing is that we agree to contribute material, and the site administrator should be happy and/or paid for their efforts, which I suspect would be substantial using either system. In other words, setting up a Wiki site may be easy, but protecting it from adware while developing useful content may in fact be easier with Plone. I leave the debate to others.

-Greg

From: iebele <[email protected]>
Date: November 2, 2006 11:53:41 PM PST

Hi Greg,

I've checked plone. I am not convinced that this will encourage people to work on the documentation. I haven't seen convincing running examples yet - maybe others have ?

Concerning Wikipedia:

Please have a look at http://www.mediawiki.org/wiki/MediaWiki.

This is a free software distribution which requires only MySQL, Apache and PHP to run.

When this wiki software is installed on a server, it /is/ a controlled environment. Most important feature imho is that only registered users can edit articles.

What kind of funding is required ? A webserver ?

-Iebele

_______________________________________________
Radiance-general mailing list
[email protected]
http://www.radiance-online.org/mailman/listinfo/radiance-general

Hi,

once more the documentation thread, seams that Greg wants us to get something done before the end of the year :wink:

It is possible to enforce authentication in Wikis, while I doubt that ideas like access rights, user management and publishing workflow are Wikis' strengths. One the other hand, many of us are familiar with wiki-syntax, and if the idea is to get a platform where everyone can just start entering his ressources, this may be a solution. Actually, we already had such a Wiki for some time in the past, and Schorsch is maintaining a very useful lighting-wiki:

http://lightingwiki.com/FrontPage

I opted for a more (pre-)structured system, more in a classical content management way, with users, authors and editors, and with the possibility to generate offline-documentation. I have a demo-installation up and running at

http://radiance.free-architecture.org

The installation is based on Drupal (www.drupal.org) and allows authenticated users to create and edit content, while this has to be approved by editor users before being published. Drupal allows not only pdf-export, but also ex- and import of chapters of its "book"-document-type, allowing offline editing. For Radiance, I would like to enable two more features, cvs-access integrated in the content management (which would require to have the Drupal set-up and the cvs-repository on the same machine) and Tex-input, because Radiance documentation (and useage :wink: relies a lot on maths... For Tex, I would have to extend the space I rent from my provider a bit, and I would do so if I knew that there is interest in this.

Besides, there is a third option, a directory linking to external ressources, as Axel's webring project, which was an advanced keyword-based system.

Anyway, I just wanted to offer again others here to play around with the installation and also to maintain it for some time (I mean more then a year), given that there are one or two willing to do some editor-work like approving new registrations, reviewing the articles / contributions etc. If there is a decision for another kind of documentation, I will stop these efforts and try to contribute there. Anyway, I think we should take this decision in the not too far future, as all those small documentation projects eat up our time and ressources, and cause a lot of frustration if there is no visible success and acceptance.

BTW, IMHO we face not a technical or financial problem - we have to motivate people to spend their spare time on a project where they have to work together for free and not only for some weeks. That is why we have so many small projects and few working examples of large maintained sites...

CU and have a nice week-end!

Lars.

Greg,

We can try MOODLE, it's a PHP aplication, with very nice features like wiki,
fórum, chat, etc.

I have used this for two years in my classes in Universidade de Brasilia
(Brazil)

It's possible to control the login and administration is very easy.

"Moodle is a course management system (CMS) - a free, Open Source software
package designed using sound pedagogical principles, to help educators
create effective online learning communities. You can download and use it on
any computer you have handy (including webhosts), yet it can scale from a
single-teacher site to a 50,000-student University. This site itself is
created using Moodle, so check out the Moodle Demonstration Courses or read
the latest Moodle Buzz."

Please, look at

http://moodle.org/

Nice to hear from you

vangelis

We tried a Wiki for Radiance already and it didn't go anywhere, and

was inundated by adware. I don't really blame Wiki for this -- the

problem was more lack of groundswell and necessary controls, which

I'm sure we could remedy if we were a little more organized.

I am not versed on the merits of or differences between Plone and

Wiki, and I know very little about either. Both Peter Apian-

Bennewitz and Daniel Fuller (the sysadmin for LBL's website) say

Plone is better, but you would have to ask them for details. I'm

willing to trust others' judgement on the matter, as I have no

expertise in the area of web management. I can make some simple

HTML, and that's about it.

The important thing is that we agree to contribute material, and the

site administrator should be happy and/or paid for their efforts,

which I suspect would be substantial using either system. In other

words, setting up a Wiki site may be easy, but protecting it from

adware while developing useful content may in fact be easier with

Plone. I leave the debate to others.

-Greg

Hi Lars,

From: "Lars O. Grobe" <[email protected]>
Date: November 4, 2006 5:23:45 AM PST
...
BTW, IMHO we face not a technical or financial problem - we have to motivate people to spend their spare time on a project where they have to work together for free and not only for some weeks. That is why we have so many small projects and few working examples of large maintained sites...

I agree, which is why it's important to have an officially sanctioned, long-term solution to the hosting of web documentation. No one can afford to spend time developing content without assurance that it will be maintained and accessible over the long haul. We need to plan our destination in advance of setting out. This is why agreeing on the technological solution and how a site will be supported is important now. Later, it will be too painful to "switch boats in the middle of the river" as we say.

-Greg

Hi All,

I just want to follow-up on this a bit.

Clearly there are a lot of CMS options such as Wiki and others that have already been mentioned. I think though rather than revisiting what tool to use, we really need to focus on what content would be valuable, how it is organized and who would be interested in producing what content. I think that we really need to rely on care and thoughtfulness that Peter A-B and Daniel Fuller have already given to what is the appropriate solution for managing the content, in this case Plone.

There is a huge amount of valuable information that gets generated on this list. However it is sometime difficult to realize the value because one has to dig through email archives. There are a lot of topics that once resolved could do with some kind of summary, how-to, faq, mini-faq (whatever you want to call it). I know there are probably several instances where I can contribute some content for example. Perhaps we need to start to get people lined up for contributing to various topics based on Greg's previous outline?

I. Installation and Set-up
    A. Standard (UNIX) distirbution
    B. Radzilla
    C. Windows alternatives
    D. Other packages

II. Tutorials
    A. Basic
    B. General, Advanced
    B. Electric Lighting
    C. Daylighting

III. Input
    A. CAD links and conversion tools
    B. Photometry & Sky models
    C. Generator programs
    D. Scene processing (xform, replmarks, oconv, etc.)

IV. Computation
    A. Rendering (batch & interactive)
    B. Illumination calculations
    C. Executive programs (rad, rayfront, etc.)

V. Output
    A. Image processing
    B. Image viewing
    C. Image format conversion
    D. Graphing & plotting

I note that there is no section on materials. Perhaps there needs to be an item E in section III Input for materials. And perhaps as a sub item there should be something on translating glazing data from Optics to Radiance, for which I will put my name down as writing something about.

-Jack

···

--
# Jack de Valpine
# president
#
# visarc incorporated
# http://www.visarc.com
#
# channeling technology for superior design and construction

Hi All,

I just want to follow-up on this a bit.

Clearly there are a lot of CMS options such as Wiki and others
that have already been mentioned. I think though rather than
revisiting what tool to use, we really need to focus on what
content would be valuable, how it is organized and who would
be interested in producing what content.

I want to support Jack on this point. Though a big part of us
has some experience with setup and administration of some kind
of content management/markup/publishing system we should focus
our discussion on the things we want to see on the system and
the way how we are going to use it, not how this could be
implemented with system XYZ.

In fact, I think that all popular systems will support the features
we need. Since there seems to be a consent about raising and
spending some cash for the setup and maintenance I would suggest
that we create a 'wish list' (specification) and ask a service provider
or consultant to do the configuration for us. This could as well be
something else than Plone, provided that the chosen SP has better
experience with it and can implement our features.

There is a huge amount of valuable information that gets generated on
this list. However it is sometime difficult to realize the value because
one has to dig through email archives.

This could be a possible feature of the new platform. Should the
mailing list migrate to the CMS as well, should we only have a
'connector' to reference and archive emails from the lists or can
we do with a simple externally created digest page for each month?

My personal wish list for the system is this:

1) transparency of content management and storage
    this is more of an admin issue, but should we decide to have
    a hosting solution, guaranteed access to the data and backup
    is a feature we have to request

2) authentication
    could be weak and simple, though, this is mainly to prevent
    excessive spamming and point 3

3) controlled editing
    I like the instantaneous access of wiki pages. But in this
    case I'd prefer to have a dedicated editor for each topic
    who controls and edits the content of the page. I like the
    idea of a 'shadow page' that's open for everyone to write.
    That keeps writers with a short attention span interested.

4) cross referencing
    Judging by our current content structure we will have several
    topics which a dealt with in different places. There should be
    an easy way to navigate between these connected pages. Wikis make
    that very easy - but also very messy. I hope we can find a better
    solution.

5) support for different content types
    there will be at least:
    - plain web pages with images (reference, tutorials, etc)
    - code samples
    - probably quite a few equations mixed in the text
    - PDF and Powerpoint documents from the workshops
    - source code (CVS controlled?)
    - mails (see above)

6) external editing
    Those of us who will write a lot will prefer to use their
    own editor of choice instead of a browser text box. Maybe
    there's a chance for revision control as well.

7) PDF output
    I'd like to be able to 'dump' selected chapters in a PDF
    document. That will make a revised edition of RwR easy -
    and of course useless.

8) email notification/reminders/digests
    basic feature i guess

9) navigation and appearance
    It should be easy for occasional users to find their position
    within the content structure and find related content. It's
    amazing how complicated web pages can be.

In my opinion those are the most important features the system
should provide. Order and relevance is of course open to discussion.
I'm sure someone else will find other features that should be
included or identify some we can do without.

Some of the points above need further detailing (like the editing
workflow) but we could agree on the general functionality we expect
from our new home in cyberspace.

I'm sorry I will be away from keyboard and broadband for the
next week. So please do not feel offended if I can not answer
any replies to this message.

And of course the standard disclaimer:
I'm happy to contribute to the documentation project whatever
I can and in whatever form it will appear.

Regards,
Thomas

···

On 4 Nov 2006, at 18:56, Jack de Valpine wrote:

Hi All,

I appreciate Thomas' notes and thoughts. I think that people obviously have a lot to contribute when it comes down to it. I really think though that we need to just assume that the CMS is going to be Plone. This looks to be quite a robust tools with a wide range of functionality. Let's move the discussion up to the next level please.

Again what we need to do is identify what some valuable content areas are and who can contribute content. Greg has already put some energy into a preliminary outline of content areas. He can't write everything. So who out there is ready willing and able? What are you able to contribute? Where do we have content (papers, presentations, whatever) that with some editing could be contributed? Where do they fit into the mix?

Here is what Greg, originally suggested in his initial email on the topic:

    I strongly encourage others to rearrange these topics, change names,
    add categories, etc.

OK. I am not sure the best way to keep track of this and/or if there should be an approval process. We need an item as follows:

Materials

    primitives
    modifiers
    acceptable/typical ranges
    how to correctly define a trans material!
    how to incorporate glazing information from Optics
    procedural materials (eg modifiers using the .cal functional language)
    methods for sampling (measuring) physically materials

Obviously some of this comes from existing content, some of this probably needs to be updated, some could perhaps be integrated from other sources (assuming their agreement), for example Georg has a really excellent diagram/explanation that I think goes a long way to explaining trans materials, and some needs to be written or codified from multiple email/list exchanges.

Another possible area where I know at least two other have some interest (Lars, Francesco and myself at least), running distributed jobs on computing clusters.

I guess I will leave it here as my thoughts are not extremely well composed at this point.

Best,

-Jack

···

--
# Jack de Valpine
# president
#
# visarc incorporated
# http://www.visarc.com
#
# channeling technology for superior design and construction

Hi again,

I won't post anything any more regarding cms/software for now, if everyone wants Plone, I have nothing to argue against it (as I do not know it) except that I do not see a reason to get an expensive solution for a task that should be simple to implement (meaning that a setup for a working site should be done in a day and without the need to install specialized software). So if someone can do what we need with Plone without spending much money (at least me I do not earn money with Radiance, so my budget is, ahem, limited), do so :slight_smile:

I have something to throw into the content discussion. As I see it, Radiance provides users with several learning / support ressources, and not all of it has to / can be covered by a website.

More or less everyone will start by installing the software. Those who do so will first look for an installation guide at the same location where they get the software, it should be linked from the download page and be available as a file called INSTALL.

Than they will start to play around, and we have some kind of a "guided tour" thru Radiance with the tutorial that comes with Radiance. This could be transformed into something more html'ly, like an illustrated step-by-step tour which is something that can be done easily in html, especially if I make the tutorial up with some more hypertext, e.g. linking from the commands used in the tutorial to the online manpages.

Everyone who decides to do a serious work with Radiance (as well as most who do anything with light simulation software) will buy the book "Rendering with Radiance" than, and will get all the ressources of the basic work with the system and the underlying theory from there.

Because we are all lazy sometimes and don't immediately find what we are searching, users will continue to ask on the mailing list, and that is what could be improved a bit by installing a FAQ - not by developing any kind of structure and topics, but by analyzing the archives of the mailing lists.

Than, what is left, what is really missing right now, and what could really be handled by the website? I think it is mainly information that is

1) subject to (frequent) changes, like new / changed tools and features (the mesh type, function files, import- export workflow which always depends on the current software environments)

2) too specialized to be covered in the book in every detail, like function files, distributed rendering, materials

3) updated libraries, for materials, light sources, textures

4) updated links, related projects (e.g. the radzilla project, whih is not and cannot be covered in the book, but is an exciting development people want to know about)

5) projects, people, papers (also the workshop cd-images)

So basically, I think we should not try to rewrite the tutorial or the book in a website, and to keep this in mind when we define a structure.

And yes, as others have been promising before me, yes, I will do my best to put my experiences into this project, and if it is only to learn where I understood things wrong in the past ;-)))

CU Lars.