[Bf-docboard] my first impressions about the new documentation system
Gaia
gaia.clary at machinimatrix.org
Tue Sep 2 15:59:40 CEST 2014
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
More information about the Bf-docboard
mailing list