[Bf-docboard] coder - doc team meetings

[Kesten Broughton]

Tacking documentation on to the weekly meeting would be fine as long as
there is a spot for it in the minutes and a public call made.  Last week,
two individuals were posting questions to help them with documentation
writing, both posted several times and neither got a response.

I have never had the release notes turn up on a search engine search, so
that's kind of an insider solution unless we advertise it somewhere.  The
problems is, right now, a lot of the wiki looks like
http://wiki.blender.org/index.php/Doc:2.6/Manual/Textures/Influence/Particles.


The "please do not contribute" notification has been up for over a month.
Perhaps readers should also be directed to the release notes for newer
features.

The problem is, there are a lot of features with totally new GUI or API
since 2.49 that don't, as far as i know, have any documentation anywhere.
(perhaps there is an archive of release notes somewhere?)  What I am hoping
for is something like the code area
managers<http://wiki.blender.org/index.php/Template:ModulesOwners>list
where each manager would be responsible for asking documentation
questions in that domain.

In my case, I wanted to update the rigidBodiesConstraints documentation.
Documentation i can find is for 2.49 and doesn't explain ConeTwist joints
very well at all.  After looking at the C++ code it turns out there is a
probable bug.  Basically, the solver is unstable when the angles go beyond
the requested angle limits.  I heard it stated last week that there are 175
outstanding bugs in blender currently.  I would suggest it is double that
on sections of code that have poor to no documentation, because without
that, users have no way of knowing what the proper behaviour should be - so
they don't submit bug reports.  In my case, Erwin Coumins could not be
reached and it took 2 months to contact Benoit Bolsee.


kesten

On Sat, Dec 24, 2011 at 11:03 AM, Brecht Van Lommel <
brechtvanlommel at pandora.be> wrote:

> Hi,
>
> Pep, there is already a wiki manual, which also doubles as a reference
> at the moment, so in a way this is already an ongoing project, but it
> needs more people contributing. There's plans to split have a separate
> reference manual, and of course it would be good avoid duplicating
> work there. But I guess you may have already discussed this with wiki
> documenters in #blenderwiki?
>
>
> Documentation can just be a regular sunday meeting topic, not a
> separate meeting, it now gets discussed often anyway, and the length
> of the meeting varies so it's difficult to pin down an hour.
>
> Meetings are a nice way to give status reports, ask for volunteers and
> make decisions, but we should not try to make this the place where
> developers explain how a feature works. This can be done anytime, over
> irc, mail, mailing lists, .. it's not efficient to do this in a
> meeting when there is little time and many people talking through each
> other. Also due to time zones or other commitments, it's not easy for
> everyone to be online at the same hour.
>
>
> For new features, mainly I think we're missing a place for developers
> to request certain things to be documented, and one or more people to
> do get this organized, keeping track of what needs to be done and
> helping documenters get started and connecting them to developers.
>
> What I'd propose on the developers side, is to keep the release notes
> for the next release updated on a weekly basis, and add markers there
> about where help is needed in documenting. The release notes need to
> be written anyway, and that also means documenters don't have to sift
> through the important/unimportant commits and try to understand them.
>
> Brecht.
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://lists.blender.org/pipermail/bf-docboard/attachments/20111225/18470a79/attachment.htm