POV-Ray : Newsgroups : povray.documentation.inbuilt : Documentation Review? Server Time: 23 Oct 2019 03:17:14 GMT
  Documentation Review? (Message 1 to 10 of 10)  
From: Jim Holsenback
Subject: Documentation Review?
Date: 11 Mar 2009 15:12:19
Message: <49b7d4d3@news.povray.org>
There was one side benefit from getting the distribution documentation on
the POV-Wiki. I've made some observations that I'd like to share. I think
there an opportunity to "up our game" as they say and improve the content,
and at the same time come up with some best practices or editing guidelines.



First off I'd like to say that as documentation goes we are in much better
shape than most other applications. The original architects should be
commended for an outstanding job. I'm hoping that my comments are taken with
that in mind.



The biggest challenge in a collaborative effort is being consistent in
style. Style in presentation and style in the programming that produces the
content are the two topics I'd like to address.



1. One obvious presentation issue is different ways of presenting
preformatted <pre></pre> passages of SDL. This is a pretty simple example,
but I think in gets the point across.



sphere {0,1 pigment {rgb <1,0,>}}



vs.



sphere

{

  pigment {rgb <1,0,0>}

}



The preformatted blocks are real easy to spot, the have a dashed outline.
Look through the tutorial and reference sections and you'll see what I mean.



2. This issue is a little bit about presentation and programming style ..
links to keywords or other sections embedded in narrative text. Sometimes
that's appropriate but other times it can be a bit messy. How about a "See
Also" section at the end of narratives that contain links to keywords that
were mentioned in the preceding passage.



3. This ones a programming style issue, and I'm willing to chalk this one up
to me just being to darn picky, but here goes anyway. Certainly html and
Wiki markup doesn't care but I did translate <PRE> to <pre> and the like in
an attempt to enforce a consistent style for the downstream programming
needed to complete the project.



4. Quote marks .. sometimes links had quotes around the link, other times
quotes in the clickable part. I even found several with punctuation marks in
the clickable part, or almost an entire sentence as the clickable portion.


I'll stop for now in case this thread fizzles ..



Jim


Post a reply to this message

From: Warp
Subject: Re: Documentation Review?
Date: 11 Mar 2009 23:16:41
Message: <49b84659@news.povray.org>
Jim Holsenback <jho### [at] hotmailcom> wrote:
> 1. One obvious presentation issue is different ways of presenting
> preformatted <pre></pre> passages of SDL. This is a pretty simple example,
> but I think in gets the point across.

> sphere {0,1 pigment {rgb <1,0,>}}

> vs.

> sphere
> {
>   pigment {rgb <1,0,0>}
> }

  In my opinion the degree of SDL example code layout should depend on the
*relevance* of that specific block of code in the context of the example.

  Fully laying out eg. an object definition, as in the second example above,
makes it stand out, compared to if it was a one-liner, like in the former
case.

  The thing is, usually you only want to make the parts *relevant* to the
example stand out. The other parts are just filler code to make the scene
complete.

  Example: Most example scenes require a camera definition and at least
one light source so that the scene can be rendered and will look good.
However, if the chapter in question is *not* talking about cameras and
light sources, then the exact details of the camera and light source in
the example are irrelevant.

  For example, if you were giving an SDL scene as an example of how to use
a pigment map, and you want the example to be complete (ie. you can simply
put the example in a .pov file and render it, and you'll get the example
image), the most important thing the example is trying to convey is the
object and its texture (which contains the pigment map). The camera and
light source are completely irrelevant in this example.

  Thus, in my opinion, it's *good* to make the camera and the light source
definitions one-liners, but fully laying out the object being exemplified.
This makes the object (and its texture) to stand out, while the irrelevant
camera and light source definitions are submitted to just a mandatory filler
role which don't take but 2 lines of visual space in the example code.

-- 
                                                          - Warp


Post a reply to this message

From: clipka
Subject: Re: Documentation Review?
Date: 12 Mar 2009 00:40:00
Message: <web.49b8595634db7005801985dd0@news.povray.org>
"Jim Holsenback" <jho### [at] hotmailcom> wrote:
> 3. This ones a programming style issue, and I'm willing to chalk this one up
> to me just being to darn picky, but here goes anyway. Certainly html and
> Wiki markup doesn't care but I did translate <PRE> to <pre> and the like in
> an attempt to enforce a consistent style for the downstream programming
> needed to complete the project.

As a matter of fact, HTML officially *does* care: Uppercase tags are deprecated
ever since the W3C chose to go for xhtml (i.e. getting HTML to be compatible
with well-formed xml).


I think it's a good thing to address such inconsistencies, and the earlier the
better (otherwise they'll tend to accumulate, and eventually a lot of
contributors will cease to bother about consistency & style altogether), except
that I myself wouldn't have the patiente to do that for existing code.


Post a reply to this message

From: Jim Holsenback
Subject: Re: Documentation Review?
Date: 12 Mar 2009 10:08:10
Message: <49b8df0a@news.povray.org>
"Warp" <war### [at] tagpovrayorg> wrote in message
news:49b84659@news.povray.org...
>   In my opinion the degree of SDL example code layout should depend on the
> *relevance* of that specific block of code in the context of the example.

hadn't thought about it like that .... a good entry point!

>   The thing is, usually you only want to make the parts *relevant* to the
> example stand out. The other parts are just filler code to make the scene
> complete.

I toyed with the idea of wrapping those preformatted text blocks in the
<source> (a highlighting extension) but then that would only make it pretty
for the Wiki version NOT the distribution versions (unless some style was
defined). Over use of bold and italic can be messy as well. Simple, obvious
is what I'm looking for .... good comments. I'll let it percolate for a bit
a see what bubbles up!

Jim


Post a reply to this message

From: Jim Holsenback
Subject: Re: Documentation Review?
Date: 12 Mar 2009 10:15:22
Message: <49b8e0ba@news.povray.org>
"clipka" <nomail@nomail> wrote in message
news:web.49b8595634db7005801985dd0@news.povray.org...
> As a matter of fact, HTML officially *does* care: Uppercase tags are
deprecated
> ever since the W3C chose to go for xhtml (i.e. getting HTML to be
compatible
> with well-formed xml).

well yikes ....

> I think it's a good thing to address such inconsistencies, and the earlier
the
> better (otherwise they'll tend to accumulate, and eventually a lot of
> contributors will cease to bother about consistency & style altogether),
except
> that I myself wouldn't have the patiente to do that for existing code.

there were some frustrating moments with the perl script in dealing with yet
another variant of those bloody <linkto> tags, I'm glad to hear you agree on
the consistency issue, I thought I might catch some flack for bringing it
up!

Jim


Post a reply to this message

From: ingo
Subject: Re: Documentation Review?
Date: 12 Mar 2009 21:03:09
Message: <Xns9BCCE04D7D6E8seed7@news.povray.org>
in news:49b8df0a@news.povray.org Jim Holsenback wrote:

> "Warp" <war### [at] tagpovrayorg> wrote in message
> news:49b84659@news.povray.org...
>>   In my opinion the degree of SDL example code layout should depend
>>   on the 
>> *relevance* of that specific block of code in the context of the
>> example. 
> 
> hadn't thought about it like that .... a good entry point!
> 
> 

In addition to Warps comment, that I fully agree with, in many cases 
all code not relevant to the item to be illustrated, like cameras, 
lights etc could go to the end of the scene(file).

ingo


Post a reply to this message

From: Jim Holsenback
Subject: Re: Documentation Review?
Date: 15 Mar 2009 12:29:15
Message: <49bcf49b@news.povray.org>
"Jim Holsenback" <jho### [at] hotmailcom> wrote in message
news:49b7d4d3@news.povray.org...
> 1. One obvious presentation issue is different ways of presenting
> preformatted <pre></pre> passages of SDL. This is a pretty simple example,
> but I think in gets the point across.

Something a bit more specific and more to the point of what I'm talking
about ....

Documentation:Tutorial Section 3.2 ....

Up until this page the SDL style was pretty consistant, then it changes at
"Writing the polynomial Vector" .....

from:

sphere {
  .....
  .....
}

to:

sphere
{
  .....
  .....
}

Am I picking nits to be pointing this out?

Jim


Post a reply to this message

From: clipka
Subject: Re: Documentation Review?
Date: 15 Mar 2009 14:35:00
Message: <web.49bd119e34db7005ac7b5ac70@news.povray.org>
"Jim Holsenback" <jho### [at] hotmailcom> wrote:
> Am I picking nits to be pointing this out?

Let's put it this way:

- This is a matter of coding style.

- Coding style doesn't really matter.

- However, *Consistency* of coding style *does* matter.

Reading code is easiest if you are used to the coding style it uses.
Reading code with a particular style helps you get used to it.
Therefore, reading code with a consistent coding style is always easier than
reading code with inconsistent style.

For example, consider the following code (using C here):

for (i = 0; i < n; i ++)
    {
    if (i % 2 == 0)
        {
        ...
        }
    foo (i);
    }

for (i = 0; i < n; i ++)
{
    if (i % 2 == 0)
    {
        ...
    }
    foo (i);
}

for (i = 0; i < n; i ++) {
    if (i % 2 == 0) {
        ...
    }
    foo (i);
}

for (i = 0; i < n; i ++) {
    if (i % 2 == 0) {
        ....
        }
    foo (i);
    }

There's no problem finding the closing braces for any of these statements even
across large blocks of code - once you know the pattern. But woe if you
intermix them!

for (i = 0; i < n; i ++)
    {
    if (i % 2 == 0) {
        ....
    }
    foo (i);
    }

Uh, yeah - perfect...

Even if they're never mixed in the same function, you'll still have problems
reading functions fluently if there is not a consistent pattern across the
whole code, or at least within a module.

The bottom line is this:

If you have the time, feel encouraged to "streamline" the coding style used
throughout the documentation. Don't worry which particular one is best -
because the best one is the consistent one.

If you have *plenty* of time, write some coding style guideline for the
documentation, so that future contributors can easily adapt their code to it.

If you have an *abundance* of time, put some thought into every aspect of that
coding style, trying to figure out which variant is best.

Whatever you do - be warned that some people *will* criticize the particular
coding style you choose, whatever that may be (even if - or maybe especially if
- you come up with a detailed rationale why you choose it), but be assured that
whatever style you go for is probably a good choice. I've never come across any
coding style that didn't have any drawbacks at all, so just go with whatever you
personally like best.

After all, you're the one taking up the task of "consistifying" the doc code
samples, so why the heck shouldn't the style reflect *your* personal
preferences?!

Of course you'll probably want to ask Chris Cason about this, as it would be
prudent to use the same coding style as in the code snippets provided by the
Windows GUI, the standad include files, and the sample scene files - but I'd
expect the answer to be thanks for volunteering to streamline *all* of these to
whatever style you deem fit ;)


Post a reply to this message

From: ingo
Subject: Re: Documentation Review?
Date: 17 Mar 2009 21:15:59
Message: <Xns9BD1E27EE8C31seed7@news.povray.org>
in news:49bcf49b@news.povray.org Jim Holsenback wrote:

> "Jim Holsenback" <jho### [at] hotmailcom> wrote in message
> news:49b7d4d3@news.povray.org...
>[...] 
> from:
> 
> sphere {
>   .....
>   .....
> }
> 
> to:
> 
> sphere
> {
>   .....
>   .....
> }
> 
> Am I picking nits to be pointing this out?
> 

MMmmm yes and no. I tried to present a uniform style of coding in the 
docs but didn't really succeed. In a discussion on the matter Warp once 
pointed out that users/newbies should see different coding styles in 
the docs as they will also encounter them in the wild.

There is no 'standard' coding style for POV-Ray, so in that regard Warp 
is right, yet IMO the style in the docs should be consistent (as 
consistent as possible). Maybe add a chapter on style showing the 
differences, but .... beware, before you know the phrase "bain dead" 
will be used in discussions on the matter of the "right" coding style.


ingo (who still hasn't looked at your efforts on the wiki and is 
ashamed)


Post a reply to this message

From: Jim Holsenback
Subject: Re: Documentation Review?
Date: 18 Mar 2009 12:04:42
Message: <49c0e35a$1@news.povray.org>
"ingo" <ing### [at] tagpovrayorg> wrote in message
news:Xns9BD1E27EE8C31seed7@news.povray.org...
> I tried to present a uniform style of coding in the
> docs but didn't really succeed.

Well I think you got closer than you're giving yourself credit for ....

> There is no 'standard' coding style for POV-Ray, so in that regard Warp
> is right, yet IMO the style in the docs should be consistent (as
> consistent as possible).

I tend to have a fairly loose style if the code is just for my consumption,
but when it's for other eye's to disect that's another story.
I think that the most important aspect of code readability is being able to
easily spot major code blocks, loops or conditional blocks. Stuff like the
curley braces being on the same line as the keyword (or on the next line)
are being a bit too picky. I agree that warp and clipka made some good
points as they touched on those issues.

I was at a job interview last week and we had a discussion about some of
these very points, and consistency seemed to be the most talked about issue
.... we were talking about user interfaces, but I see parallel's in
documentation as well.

> ingo (who still hasn't looked at your efforts on the wiki and is
> ashamed)

haha .... I was feeling like no one cared until I realized that there seems
to be an awful lot of distractions lately .... trying to figure out what all
the politicians and bankers have in store for us next can be pretty
unsettling.

So far I've enjoyed the project, and I'm looking forward to the next part
(extracting the doc sets) and upping my skills as I dig into the PHP end of
things.

I DO appreciate everyone's comments!

Jim


Post a reply to this message

Copyright 2003-2008 Persistence of Vision Raytracer Pty. Ltd.