#1 Documentation: examples

open
nobody
None
5
2004-10-20
2004-10-20
Anonymous
No

Hi! I write this after reading "Pixie needs your help".

Something I think would improve a lot Pixie's "sex appeal"
is having complete short examples as concepts are
explained in documentation sections.

Like in the Global illumination documentation. We can
read code snippets but what would be very good is
a short but complete rib file, using default shaders.
When talking about shaders other than default shaders,
full code of small examples would help a lot too.
It would help see where the described concept fits
in the whole picture.
Without a complete file, every user reading the doc have
to reinvent the wheel, trying to see where the concept
fits with the rest.
In other words, one has to understand the
documentation before understanding the concept.
Which is not good :)
It is not about intellectual lazyness but more on focusing
on the new concept learned.

The person who writes the doc understands the concept
and thus can easily see how it fits with the rest and
should pass this knowledge.

Well.

That's how I think I could help Pixie.

Discussion