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