[Bf-docboard] coder - doc team meetings

[Brecht Van Lommel]

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.

On Wed, Dec 21, 2011 at 4:49 PM, Kesten Broughton
<solarmobiletrailers at gmail.com> wrote:
> I think it would be very beneficial to have weekly or monthly meetings
> between coders and core wiki contributors.
>
> It would be great not to have to guess the functionality of a button or
> python API call.
>
> Besides that, blender development is currently missing out on one of the
> strongest elements of Open Source programming - dedicated and free bug
> testing.  I bet there's over 100 bugs lurking in the space between what
> coders intended their work to do, and what users have "figured out" that the
> functionality does.  I've seen several people mention on the forums that
> they don't submit bug reports anymore unless they're 100% sure it's a bug -
> but that's very hard to know if there is no documentation.
>
> Mindrones, any chance that we could get Ton to bless a meeting hour each
> week between devs and doccers sometime in the new year?  Just after the
> sunday scrum might be convenient.  It could be voluntary at first, but any
> coders delinquent in their documentation could be "required" to attend
> before submitting more code.
>
> Even if a coder is producing documentation, it wouldn't hurt to have their
> work reviewed by an external party since their intimate understanding of the
> code usually leads to assuming users know something they don't.
>
> kestion
>
>
>
> On Wed, Dec 21, 2011 at 5:00 AM, <bf-docboard-request at blender.org> wrote:
>>
>> Send Bf-docboard mailing list submissions to
>>        bf-docboard at blender.org
>>
>> To subscribe or unsubscribe via the World Wide Web, visit
>>        http://lists.blender.org/mailman/listinfo/bf-docboard
>> or, via email, send a message with subject or body 'help' to
>>        bf-docboard-request at blender.org
>>
>> You can reach the person managing the list at
>>        bf-docboard-owner at blender.org
>>
>> When replying, please edit your Subject line so it is more specific
>> than "Re: Contents of Bf-docboard digest..."
>>
>>
>> Today's Topics:
>>
>>   1. Re: Blender Reference (Pep Ribal)
>>
>>
>> ----------------------------------------------------------------------
>>
>> Message: 1
>> Date: Tue, 20 Dec 2011 16:54:14 +0300
>> From: Pep Ribal <pepribal at gmail.com>
>> Subject: Re: [Bf-docboard] Blender Reference
>> To: Blender Educators and Trainers <bf-education at blender.org>,
>>        bf-docboard at blender.org
>> Message-ID: <4EF09386.2010108 at gmail.com>
>> Content-Type: text/plain; charset=ISO-8859-1; format=flowed
>>
>> I don't think it's a question of the number of writers... It's more a
>> question to organize the work at a similar level of how the developers
>> work. I would volunteer to turn my project into a community based one,
>> but as I insisted, a roadmap should be defined, a scope should be
>> defined, and leave as less as possible to improvisation... I'd really
>> love to be on board of a really structured plan.
>>
>> At least I think that things should be discussed to see if it is agreed
>> (or perhaps not) that the documentation work should be reorganized.
>>
>> I'm volunteering as a writer if we could define the work to do as a real
>> project with definite goals. If needed I can help with organization as
>> well, as I have many ideas which perhaps could be useful.
>>
>> I'm posting this message to the docboard as well. I think that this
>> topic even fits more there.
>>
>> Regards.
>>
>> Pep.
>>
>> El 20/12/11 10:31, Knapp escribi?:
>> > I made a post today with about the same idea in it. I agree with you
>> > strongly. We really need at least as many manual writers as programs
>> > just to keep up! Then there are all those undocumented bits that are
>> > out there for example,  light field, or plenoptic, photography tools
>> > in blender. You would never know they were there but I asked one day
>> > on the dev email list. I made me really sit up and wonder what else
>> > was out there in blender! I think writing your own book is the wrong
>> > way to go. What we need is a really strong manual writers group.
>> >
>> > On Tue, Dec 20, 2011 at 7:04 AM, Pep Ribal<pepribal at gmail.com>  wrote:
>> >> Hi all,
>> >>
>> >> I haven't posted anything yet, because I feel that my vision on all
>> >> this
>> >> might be a bit off of what it seems to be the way of action you all are
>> >> pointing out. However I feel that I must share my ideas. Actually I
>> >> wasn't unsure if I had to post it or in bf-docboard... However if you
>> >> think I also should post in the docboard list, tell me and I will do it
>> >> too.
>> >>
>> >> Last 2 days I've been having interesting conversations in the IRC (with
>> >> darKoram and greylica), and I think I should share my thoughts with the
>> >> rest of you.
>> >>
>> >> The thing began 2 months ago. I've been thinking on becoming BFCT for a
>> >> while, and finally I decided to go for it. However I find that the
>> >> major
>> >> problem for someone that wants to learn Blender in depth is the lack of
>> >> an in-depth up-to-date Blender reference. The wiki can definitely be a
>> >> good place to give you good hints, but I think it's far away from being
>> >> a complete reference site... To make things "worse", development goes
>> >> so
>> >> fast that documentation gets outdated easily.
>> >>
>> >> I contributed in a few places in the wiki manual (and years ago I
>> >> worked
>> >> on the manual translation to spanish), but I think that it is currently
>> >> not the resource (at least) I need.
>> >>
>> >> So I boldly decided to create my own Blender reference. My idea is to
>> >> make a "dissection" of Blender, trying and testing every bit and piece
>> >> of it, and to slowly create a brief reference (in Spanish at the
>> >> moment)
>> >> documents for myself which I could use in the future to make video
>> >> tutorials, lectures and so on. I think that such a reference would be
>> >> the perfect basis for: official manual, tutorials and video tutorials,
>> >> examinations, courses, and a long etcetera.
>> >>
>> >> So these 2 months I've been "touching everything" in Blender in all the
>> >> possible ways and forms. Result has been I start to learn a lot; at the
>> >> same time I've done a lot of bug reporting (as I push Blender in all
>> >> ways, and I find many little things), but it's hard, as ther is not a
>> >> source of complete knowledge about all Blender features.
>> >>
>> >> The problem: it's very sluggish. That is Herculean task for a single
>> >> person. However, I'm decided to continue no matter how long it takes.
>> >> And it's gonna take me ages.
>> >>
>> >> With my recent conversations on the IRC, I would like to know if
>> >> perhaps
>> >> my personal project could be integrated into the Blender community. My
>> >> goal atm is not certification, or exams, or whatever. I'm thinking on
>> >> the long run: I am for a complete in-depth up-to-date Blender
>> >> reference.
>> >> Either made by me, or rather turned into an official project. Then, I
>> >> can start thinking again on my BFCT, because I will have good material.
>> >>
>> >> If it worked ok, developers could even forget about documenting, except
>> >> for a) the release logs and b) the weekly meetings.
>> >>
>> >> As I took a master certificate on project management time ago, I'm very
>> >> aware that in every project planning is more than 50%. If a good
>> >> project
>> >> charter and plan could be designed (with all key elements of project
>> >> planning or similar), and if enough people could commit, I would
>> >> definitely change the approach from a personal project to a community
>> >> one.
>> >>
>> >> The plan should integrate: writers, reference breakdown and
>> >> assignments,
>> >> regular meetings with the developers (let's say once a week?),
>> >> schedules, definite milestones, resource management, scope, and so on.
>> >>
>> >> Regarding meetings with coders, I've been bothering them a bit those
>> >> past days, but I think that "official" meetings would give writers much
>> >> more confidence that their questions will be answered "this week".
>> >>
>> >> I think I've written too much. Well, I don't know if someone will think
>> >> I'm saying a single interesting word, but at least I could share my
>> >> thoughts. Let me know what you think.
>> >>
>> >> Best,
>> >>
>> >> Pep.
>> >>
>> >> _______________________________________________
>> >> Bf-education mailing list
>> >> Bf-education at blender.org
>> >> http://lists.blender.org/mailman/listinfo/bf-education
>> >
>> >
>>
>>
>> ------------------------------
>>
>> _______________________________________________
>> Bf-docboard mailing list
>> Bf-docboard at blender.org
>> http://lists.blender.org/mailman/listinfo/bf-docboard
>>
>>
>> End of Bf-docboard Digest, Vol 82, Issue 2
>> ******************************************
>
>
>
>
> --
>
> Kesten Broughton
> President and Technology Director,
> Solar Mobile Trailers
> kesten at solarmobiletrailers.com
> www.sunfarmkitchens.ca
> 512 701 4209
>
>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>