Keywords

Dear all,

I've been working on a new site which tries to pull all the RADIANCE
related info that is OUT THERE together. It is based on keywords and a
ranking system with voting.

The site is working, I am just waiting for our new .eu domain to go up, so
bear with me.

In the meantime, may I ask for your feedback regarding the keywords. While
I can easily add new ones as we go along, changing existing ones (or
dropping them) is more difficult. Here is what I thought:

    * AddOns
    * Ambient
    * Daylighting
    * Generators
    * HDR
    * Materials
    * Modelling
    * Patterns
    * Scripting
    * Textures
    * Tutorial

Is any of them not sensible to have?
Should any be renamed?
Other ones?

In general, where possible would it be better to
a) use the noun rather than the gerund, e.g. scripts/scripting;
b) prefer plural over singular, e.g. patterns/pattern.

I am trying to make them as consistent as possible. The site has a
suggest-new-keywords form, so adding to the list is easy-peacy.

Thanks for your thoughts

Axel

Hi Axel,

This sounds like a great plan to me -- very much along the lines of what Peter and I and others have been discussing. I guess you didn't see the proposal I put together last November (attached). Many objected to my proposal as impractical, which it probably is. Your approach sounds like it will work, though.

The keywords you have look good. You can also mine the old archive lists for other keywords, i.e.:

  http://radsite.lbl.gov/radiance/digests_html/topickey.html

To your keywords, you might add:

  CalculationParameters
  Animation
  Reference (basic references)
  Principles (method references)
  Validation
  Commands (man pages)

Rename these as you see fit to make them understandable.

I'm so glad you're doing this!

-Greg

-------------- November 2005 Radiance Documentation Site Proposal

···

-----------

BACKGROUND

Since its initial release in 1989, LBNL's Radiance software has steadily gained in capabilities and popularity to where it is now respected as the world's most advanced lighting simulation and rendering system for daylight design. Today, over a dozen commercial packages employ some version of Radiance as their primary calculation engine, and for the past four years, an international community of users, developers, and researchers have been actively communicating on a public mailing list and attending an annual workshop dedicated to this package. By a recent survey, about half of those who perform daylighting simulation (knowingly or unknowingly) use some version of Radiance. The other half employ a variety of different calculation engines, with no close second in terms of overall popularity.

The Radiance package itself consists of over 100 individual programs, which are designed to be used in combination following the UNIX "toolbox" model. This power and flexibility comes at a price, which is the time it takes to learn such a complex system. Although the basics can be handled with just a few essential commands, even these are subtle and take time to master compared to a more typical menu-driven application. Even with the help of the book, "Rendering with Radiance: The Art and Science of Lighting Visualization," potential users are scared off by the learning curve, or give up at some point in favor of simpler tools. Our most dedicated users are those who, after one or more false starts, realized that the only way to solve their challenging daylighting problems was to buckle down and learn Radiance.

Because people come to Radiance with hard problems to solve, oftentimes the basics are not enough. In many cases, they need to fathom some lesser-used aspect of the system particular to their task, and for this the primary text may not have the answer. So, they browse reference material on the Radiance websites and other sites, searching for relevant information. Failing that, or perhaps before searching, they ask the online community, who frequently know the answers already or can point to appropriate references where the answers may be found. Frequently, a respondent will take the time to work through another user's problem, to everyone's benefit. The nature of freeware encourages this sort of interaction, where people feel indebted to the software developers and to other users for support they received when they were starting out themselves.

Although there is a wealth of information available on Radiance in the form of manuals, technical reports, tutorials, articles, e-mail archives, and notes, this documentation is loosely organized and in some cases difficult to track down for the average user. This is partially compensated by Radiance's active online community, but a mailing list is not always the best or most efficient way to get information. Firstly, the troubled user must understand their problem well enough to formulate a coherent question, and English is often a second language. Secondly, the user must be willing to wait for an answer. Sometimes, it comes within hours. More often, it takes a day or two, and sometimes, if their question is poorly worded or on an obscure topic, they never get an answer at all. Even when they get an answer, it frequently begins a conversation between two or more users that takes a week or so to reach a conclusion. If you are stuck on some problem and facing a deadline, this represents precious time lost, and it would be better to spend more time up front searching the archives to find an answer without bothering the online community, if such an answer exists.

PROPOSAL

We propose to develop an online documentation system for Radiance that gathers together all extant information in a tree structure to facilitate top-down searches. At the front page, users will be able to perform keyword searches or choose from a small number of categories that will narrow their search at each level, drilling down until the system either finds a set of relevant materials, or tells the user that no information exists, suggesting a topic for a message to the radiance-online mailing list.

If the user subsequently composes a question for the mailing list with the suggested subject, the thread is followed and the outcome is then placed in the documentation tree at the point where the user originally reached a dead end. Online users will be encouraged to create a summary or conclusion for each mailing list topic, and provide additional links to relevant information for the website.

In this manner, the website will be maintained and updated by the user community in a semi-automatic fashion. A FAQ could also be generated automatically based on repeated queries. This would provide new users a place to go before they even know what questions to ask.

The basic goal of this project is to gather together existing documentation for Radiance, bringing it together in a system that permits the user community to continually improve and update the content over time. The facilities developed in this project and the lessons learned will have broader application to other LBNL software packages with active online communities, such as EnergyPlus and DOE-2(??).

RESOURCES

The project will require approximately 6 person-months for a web developer to organize the material and create the appropriate pages and link together existing and develop new tools for automatic updating. An additional 3 person-months will be required from the software's original author, for expert advice on where to find the raw material and how best to organize it. The project timeline will allow 6 months from start until the website goes public, followed by a 6-month live testing and evaluation period.

Hi Axel.

Thanks for your effort to collect all the floating wisdom.

In the meantime, may I ask for your feedback regarding the
keywords. While I can easily add new ones as we go along,
changing existing ones (or dropping them) is more difficult.

Since those are only "keywords" I expect there will be a
lot of them in the long run which could become a problem
because it generates to few or to much hits. Perhaps they
could be organized in a tree-like structure to show the
coverage of the same topic in "higher" levels.

Here is what I thought:

    * AddOns
    * Ambient
    * Daylighting
    * Generators
    * HDR
    * Materials
    * Modelling
    * Patterns
    * Scripting
    * Textures
    * Tutorial

A bit rewritten and adding Greg's and my own new keywords:

     * AddOns
     * HDR
     * Materials
       - Basic Types
       - BRDF
       - Light Sources
       - Patterns
       - Scripting
       - Textures
     * Modelling
       - Generators
       - Export/Import
       - Primitives
     * Reference
       - Basics
       - Commands
       - Methods (for experts)
     * Rendering
       - Tools
       - Parameters
         -- Ambient
     * Scripting
       - Animation
       - Examples
       - Patterns
     * Simulation
       - Artificial
       - Daylighting
         -- Skymodels/Generators
       - Urban Context
     * Tutorial
       - Basic
       - Advanced
       - Best Practices
     * Validation

So if you don't find good information for "Textures" you could
look up sub-keywords of "Materials" and try "Scripting" instead.
Combination of both would be best ("Scripting" in the context of
"Materials").

Thomas

···

***********************************************************************************
This e-mail, (and any attachments) is confidential and may be privileged. It may be read, copied and used by the intended addressee only. If you have received this in error please contact BDP immediately.

If you have any queries, please contact the sender.
***********************************************************************************
Building Design Partnership
Registered in England No 2207415:
Registered Office: Building Design Partnership Ltd, Sunlight House, PO Box 85, Quay Street, Manchester, M60 3JA, http://www.bdp.co.uk
***********************************************************************************

Hi,

wow, finally some people started a new doc effort :wink: So I just have one small addition to suggest at the moment, mostly because I had so many questions about it before...

CU Lars.

A bit rewritten and adding Greg's and my own new keywords:

     * AddOns
     * HDR
     * Materials
       - Basic Types
       - BRDF
       - Light Sources
       - Patterns
       - Scripting
       - Textures
     * Modelling
       - Generators
       - Export/Import
       - Primitives

[insert here] - Referencing with instances, xfroms, alias and inherit

···

     * Reference
       - Basics
       - Commands
       - Methods (for experts)
     * Rendering
       - Tools
       - Parameters
         -- Ambient
     * Scripting
       - Animation
       - Examples
       - Patterns
     * Simulation
       - Artificial
       - Daylighting
         -- Skymodels/Generators
       - Urban Context
     * Tutorial
       - Basic
       - Advanced
       - Best Practices
     * Validation