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

[Trouble Daemon]

Hey,

Glad to hear some of your thoughts on the sphinx system, and no problem
with the help.

I wonder myself about the specifics of things like internationalization,
but I suspect branches (as campbell mentioned) will be the way forward. The
question there, however, is what kind of process or methods will the
translators use to keep track of what needs to be done. Someone will need
to sit down (even if only in a dry-run fashion) and tests the waters a bit
to see what a good approach to keeping track of the changes is.

I also threw together another video (~30min) for you to see a big more of
the workflow of the previous video that I thought might help you:


https://download.blender.org/ftp/dan/manual/blender-manual-git-squashing.ogv

and I suppose the original (~6min) video can be shared for those interested
as well:

  https://www.youtube.com/watch?v=tfMAxEe2ohk

As for rst, don't feel bad! It kicks my arse a bit too, which is why I
started with a bunch of simple changes first, and slowly try learn a bit
more over time. I still don't have a clue how to fix half the problems
though. Then again, I never really knew wiki markup either :)

Anyway, look forward to seeing you back documenting when things get ironed
out a bit more, ttyl. o/


Dan



On Tue, Sep 2, 2014 at 9:59 AM, Gaia <gaia.clary at machinimatrix.org> wrote:

> 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
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20140902/fcdb9f06/attachment.htm