[Bf-docboard] Propsal: fundamentals, citation

Fri Jul 1 13:13:20 CEST 2016

Hello Julian,

Thanks for your interest.

It a step from central glossary to a structured.
The scope is not wider than defined in the current manual.

The work is already _done_ (phase 1).
It benefits by cleaning up the whole manual (phase 2).

Which is move non Blender specific content to glossary.

Kind regards
Tobias

Am 30.06.2016 um 15:48 schrieb Julian Eisel:
> 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 tohttps://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
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> https://lists.blender.org/mailman/listinfo/bf-docboard

-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20160701/efe4d70a/attachment.htm 