[Bf-docboard] coder - doc team meetings

Sat Dec 24 19:29:52 CET 2011

Hi guys.

Brecht,

I have a pending talk with mindrones on the IRC; I haven't discussed
much yet. However, following his advice I wrote my ideas on the topic
in my wiki user space (user Pepribal there).

Regarding the documenters-coders meeting, obviously I would rather go
for an "ask whener you need it" than a "wait until the meeting". I was
just proposing some mechanism to avoid being ignored in the IRC which
understandably has happened: in a Groucho style, I'd say "I would also
ignore myself if I just could be someone else for a moment" ;). So
yes, much better as you say.

The idea I'm proposing takes some doc workload from documenters.
Perhaps they could just write the idea briefly, then the documenter
tries to understand it: if he/she does, done; if not, ask in the IRC
whatever that is not understood, and done.

As I said, I'm already working in my own "Blender Referencish" thingy.
There is the phantom menace of the eternal proposals "this would be
nice", "that would be good", "this could be better", "let me think
about it for 7 months" and start over. So, well, if something can be
started, you can count on me, meanwhile I keep rolling. Perhaps
sometimes duplicated work is preferred to lack of decision?

At the end of the day, what I really wish is to learn Blender. And for
that I need to have the peace of mind that would give me a good
reference out there, updated and exhaustive. If that is finally set
up, and the organization makes sense, no doubt I'll be there with you
guys.

Merry Christmas everyone!!

Pep.

2011/12/24, Brecht Van Lommel <brechtvanlommel at pandora.be>:
> 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
>>
> _______________________________________________
> Bf-docboard mailing list
> Bf-docboard at blender.org
> http://lists.blender.org/mailman/listinfo/bf-docboard
>