[Bf-docboard] Getting involved and workflow questions

[Helmar Suschka]

Hello,

I’m willing to jump in with contributing to the Blender documentation
project. I have a few questions before I can start working, most of
them related to the general workflow and collaboration between
contributers.

The Sphinx/reST stuff is no entry barrier for me since I already work
a lot with similar publishing solutions (mostly AsciiDoc and its
DocBook toolchain). But I’ll have to adjust to the obstacles the use
of Subversion introduces.

1) How to do quick “drive-by” changes?

I’m used to do spontaneous corrections and improvements all over the
place when I see the opportunity, e.g. when I’m working with Blender
and the manual and stumble upon something (bad description, typos,
layout errors, etc.). I’d just fix it right away. So -- without
branching and local commits, is there a way to do this independently of
other work in progress? Would it affect other contributors that may be
working on different sections? Or shouln’t I do this at all because
it’s too complicated to coordinate with the current system?

2) How to collaborate with someone on the same content?

There are some broader tasks claimed where I’m unsure if I can do
something that may overlap with them or have to ask first every time.
There’s no way to see more detailed if someone is actually working
right now (has made local changes that are not visible to others yet)
and on what exactly. This could block whole sections from faster
improvement by discouraging contributors to touch anything related to
not do double or otherwise useless work. How can we get around this in a
least time-consuming way?

3) How to handle WIP changes without freezing everything local?

No one can see changes unless they’re either committed or provided as a
diff. Committing directly means having things in production stage
without any review (not good, and it forces bigger, complete commits
instead of more granular ones). Providing a diff for review on every
change freezes any further local changes until review is complete
(otherwise you’d mess up later diff creation). This seems to be a
hurdle for efficient parallel proof-reading while other work can
continue.

Maybe there are already solutions to some of that or we can find some.
It’s all about being able to work fluently and spontaneously when
there is time for it, without too much administration overhead.

I’d like to work on some of the basics first to get used to it
(unless it collides with Gaia’s work, see question 2). I found some
naming inconsistencies in there as well as redundant passages and
unfitting images.

Later on I’d move to other sections and especially have some focus on
video editing.

I’m looking forward to contribute my first changes soon.


-- 
- Helmar