[Bf-docboard] my first impressions about the new documentation system

[Gaia]

So after a few days of working with the new documentation system
i need a break. Here is my personal experience with it. And i am
sure others will have completely different experiences. However...:

1.) Installing the documentation system was not really complicated
     in my case, but my computer was already setup with a lot of tools
     like cygwin python 2.7, git. So most of the environment was up and
     running. It took me a while to understand that i also need pip
     (although i forgot where it became important). But all worked.

2.) registering as documentor was easy. actually i only needed to add
     myself as subscriber here:

     https://developer.blender.org/tag/documentation/

3.) getting the documentation repository was easy as well.
     No surprises here. But i am also used to work with the
     blender git repository, so i already knew how to get this
     to work.

4.) I was able to build the documentation from my Cygwin shell just by
     calling make. It took about 15 minutes to "compile" the docs, but
     only on the first build. from then on it was building in about 15
     seconds. I know that when you do not have Cygwin, then make won't
     work. But there seems to be a bat file for building on windows.

5.) I tried to get comfortable with the RestructuredText syntax and i
     found it a bit weird to use. I stumbled a lot over writing wrong
     indentation, and missing or too many blank lines and oddities like
     that. well, i can imagine that one can eventually get used to this.
     At the end its a bit like programming the documents and you need to
     learn yet another programming language...

6.) I find the Sphinx documentation can be helpful for developers, but
     it took me always a lot of time to understand how exactly the
     syntax was for specific issues i had. Some of the descriptions i
     just could not understand. Probably because i do not know how the
     documentation system functions internally. Others may find the
     sphinx documentation is perfect to read.

7.) When i look at the compiled html files from my local browser, then
     it is almost ok. Just that the nice icons from font awesome show up
     as broken characters instead. I believe that is because firefox
     does not install the fonts when they come from a different location
     as the files. Internet explorer displays the icons fine.

8.) My first push was a disaster. I forgot to pull before pushing and
     everything broke. But i was told to create my own branch before
     pushing, so the disaster was revertible. Actually troubled helped
     me to recover. Thanks for that !

9.) I tried to make my documents pretty and nicely readable. That was a
     challenge in multiple ways:

     a.) It took me a long time to understand the sphinx directives.
     b.) Sphinx allows to create tool tip boxes. But there seems to be a
         bug which moves the box title into the box text area, and sets
         the title to the box type ("Note", "Warning",  "Error", ...)
     c.) I have organized my documents with images aligned to the right
         page border. Sphinx by default uses a one column scheme which
         works ok when you have just a few images. while it is not a big
         issue to get images right aligned in Sphinx, the results are
         somewhat odd at times:

       - when you narrow the page to simulate a cell phone display,
         then the text left to the image gets squeezed too much.
         Maybe that is just a theme issue.
       - there is no layout alignment clearing
         (in html it would be like: <div style="clear:both;"></div> )
         however i found it is possible to add that as "raw html"
         into sphinx. That is ugly but working.

10.) The hierarchy display is odd. as it can not be collapsed. Also i
      was working within the Modeling chapter which displays about 130
      entries in the left navigation bar with all hierarchy levels
      expanded, and with no indentation.

      So for now i use the browser search to find my way through the
      hierarchies.

11.) What i am missing most is instant feedback on my changes. i often
      add a few lines of text then i want to see how the layout looks.
      So i frequently rebuild the documentation which takes a few
      seconds each time.

12.) I need to switch between 3 windows:

      - edit in a text editor
      - build in a command shell
      - inspect in the browser.

But of course i can place 3 windows on my computer screen to make this
convenient.

13.) open questions for me:

     a.) How would this system work for multiple Blender versions ?
     b.) How would this system work for internationalisation ?
     c.) How would many documentors work on this system ?
         here especially: How can one know that a specific document
         is already locked by another documentor ?
     d.) How will my changes be propagated to the final online
         documentation ? are we all supposed to work on personal
         branches ? Will these branches be setup on the remote master ?
     e.) What about search ? the built in search seems to be limited.

All in all it took me some time to get used to the new system. For now
i found it a bit frustrating to use because there are so many small
issues, each of them is just a bit annoying, but all together are
a bit of a pain (for me).

So i take a break and step back to other things for a few days until i
recovered from my first impressions ;-/ then i give it a second try.

i hope that helps
cheers,
gaia