[Bf-docboard] Propsal: fundamentals, citation

Thu Jun 30 15:48:49 CEST 2016

Hey,

I have to agree with Campbell on this. It's fine to improve what we
have now, but the idea of a wider scope Encyclopedia brings really
questionable priorities. I'm not totally against such a thing
(although I'd prefer it to be separate from the manual glossary),
however starting to work on this while there is still lots of work
needed on existing parts feels really weird. To the public this might
also seem like a weird step.

Please don't see this as if we wouldn't appreciate what you're doing.
We do appreciate the effort, we just don't agree on priorities with
you. Managing priorities is a key thing in Blender development due to
our limited resources.

Cheers,
- Julian -

On 30 June 2016 at 08:22, Campbell Barton <ideasman42 at gmail.com> wrote:
> Please keep the glossary as is, or make improvements if information is
> incorrect.
> It isn't perfect, so we can edit it once in a while to improve
> different descriptions.
>
> The glossary is just to help give some extra information to the
> manual, that you like to improve it is good  -
> but you are continually pushing for it to become some much larger document.
>
> Having some new/old glossary just confuses things.
>
> There are many areas of Blender which are entirely undocumented (or
> very low quality docs).
> Spending time on some extended Encyclopedia is really not helping
> users that much as far as I can see.
>
>
> On Wed, Jun 29, 2016 at 9:48 PM, Tobias Heinke
> <heinke.tobias at t-online.de> wrote:
>> Hello Campbell,
>>
>> Fundamentals is not out of scope - because I've added few new terms and
>> these are even in scope of the glossary. as it is now.
>>
>> Terms could easily added in a centralized - it just delays the clean up to
>> later. Terms are not added often.
>>     No one added a term in probably more than six years (excluding my 2
>> terms).
>>
>> It has not to be maintained - all the terms I replaced were already wrong,
>> when they have been added years ago.
>>
>>    https://www.blender.org/manual/glossary/index.html#term-refraction
>>     (the speed of light is absolutely constant)
>>
>> Blender is not a small software program with a bunch of internal name terms,
>> where a central glossary might be sufficient,
>> but not for a complex software suite.
>>
>> Contra central glossary:
>>
>> Difficult (impossible) to clean up:
>>
>> - Finding terms that shouldn't be in the glossary.
>> - Assimilation of the classification of terms.
>>
>>    https://www.blender.org/manual/glossary/index.html#term-anti-aliasing
>>
>> A part of the definition is already taken up by the classification:
>>
>>     https://www.blender.org/manual/glossary/index.html#term-environment-map
>>
>> A lot of links are needed and the terms are not comparable, because they are
>> scattered:
>>
>>     https://www.blender.org/manual/glossary/index.html#term-topology
>>     https://www.blender.org/manual/glossary/index.html#term-straight-alpha
>>
>> Extended content looks bad:
>>
>>     https://www.blender.org/manual/glossary/index.html#term-non-manifold
>>     https://www.blender.org/manual/glossary/index.html#term-color-space
>>
>> Extended content like images is impossible.
>>
>> It's not readable top to bottom.
>>
>>
>> We could also have both:
>> The old terms sorted in.
>> The newly created ones in a glossary called "new".
>> (like the unsorted bookmarks in a browser)
>>
>> So I'm asking for a test run. It's easy revertible.
>>
>> Tobias
>>
>>
>> Am 16.06.2016 um 16:43 schrieb Tobias Heinke:
>>
>> Hey Campbell,
>>
>> Thanks for the reply.
>>
>> As I said, linking to terms still works and the definitions are still
>> compact.
>> Searching through the terms is possible thanks to the index.
>>
>> The Blender Manual never was a pure software manual (specification), it
>> can't because of the audience it addresses.
>> And Funda is even a step into the direction making the manual more about the
>> software
>> by separating the non Blender specific content.
>>
>> The problem of a centralized glossary is it get messier with every new term
>> added and cleaning it up is not fun.
>>
>> Hierarchy occurs naturally and is currently expressed by link between terms:
>>
>>     Anti-aliasing: MSAA, FSAA...
>>     https://www.blender.org/manual/glossary/index.html#term-anti-aliasing
>>
>>
>> Non of the paper I cited sofar belongs to that category technical paper,
>> in the sense of detailed information about the implementation of a
>> technique.
>>
>> I disagree, that these papers are just interesting for developers.
>> The citation fulfills the different purposes of pioneer papers and
>> recommended literature.
>> Why these pioneer papers have to be cited I have written in the previous
>> mail.
>>
>> Fundamentals doesn't becomes outdated:
>> Eric Veach PhD thesis "Robust Monte Carlo methods for light transport
>> simulation" from 1997 still holds up.
>> And Blinn will still be the one who introduced bump mapping to 3D CG.
>> c.f. http://old.siggraph.org/publications/seminal-graphics.shtml
>>
>> Tobias
>>
>> Am 15.06.2016 um 16:11 schrieb Campbell Barton:
>>
>> Am quite against replacing the glossary,
>> in computer graphics their are many cryptic terms (FSAA, SSS, gimbal
>> lock, ngon... etc),
>>
>> As an author you can write :term:`FSAA` which links to the glossary,
>> if the term is missing, you get a warning and you can add it.
>> The descriptions generally short and to the point, with links to
>> expanded information where appropriate.
>> There is also no need to manage page hierarchy, add new categories,
>> think about where each term *belongs*.
>> its a big list which is easy to search and linked to as needed.
>>
>> What you suggest is a more general document on computer graphics
>> fundamentals which is OK,
>> but outside the scope of a software manual.
>>
>> >From reading what you have so far, its quite esoteric from a user
>> perspective and more of interest to developers, with links links to
>> technical papers on each topic.
>> People interested in such papers can find it themselves searching
>> online and don't need us to spend time on a document for this, which
>> is likely to be outdated in a few years anyway.
>>
>> eg:
>>
>> http://blender-manual.readthedocs.io/en/testing/fundamentals/physics/phy_matter.html
>> http://blender-manual.readthedocs.io/en/testing/fundamentals/computer/com_light.html
>>
>> Or, if there is some need for a document like this, I think its
>> different enough from a software reference manual,
>> that it can be maintained as a separately (which the manual could link
>> to, when it makes sense, as with any other web site).
>>
>> On Wed, Jun 15, 2016 at 5:57 AM, Tobias Heinke
>> <heinke.tobias at t-online.de> wrote:
>>
>> Hi Campbell,
>>
>> Yes, to replace the glossary.
>> First I want to keep the glossary parallel to Fundamentals and then
>> dissolve it into Funda term by term.
>>
>> Tobias
>>
>>
>> Am 14.06.2016 um 19:23 schrieb Campbell Barton:
>>
>> Hi Tobias,
>> are you proposing
>> http://blender-manual.readthedocs.io/en/testing/fundamentals/index.html
>> be moved to https://www.blender.org/manual/
>> and maintained in our subversion repository along with the rest of the
>> manual?
>>
>> _______________________________________________
>> Bf-docboard mailing list
>> Bf-docboard at blender.org
>> https://lists.blender.org/mailman/listinfo/bf-docboard
>>
>>
>>
>>
>> _______________________________________________
>> Bf-docboard mailing list
>> Bf-docboard at blender.org
>> https://lists.blender.org/mailman/listinfo/bf-docboard
>>
>>
>>
>> _______________________________________________
>> Bf-docboard mailing list
>> Bf-docboard at blender.org
>> https://lists.blender.org/mailman/listinfo/bf-docboard
>>
>
>
>
> --
> - Campbell
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> https://lists.blender.org/mailman/listinfo/bf-docboard