Re: [Bf-committers] Including documentation in BCon cycle
On Tue, Nov 8, 2011 at 7:53 AM, f.paglia...@gmail.com wrote: I'm not a developer so I see your suggestion from an artist point of view: It's an incredile pain try to figure out how a tool works! Really, I think here in our studio we spent dozen of hours in testing, defining our own ideas of what is done by a tool without really know if what we imagine is true. And this in many situation lands to not use that tool but just find another way to do something that works! I agree in the relationship: No docs = not ready for trunk Maybe it's time to hire someone to get a well documented wiki ;) Funny, I was thinking the same thing as I fell asleep last night. One person in charge of finding the problems and talking with the devs, coordinating of the writers and pulling together all the docs, links, blogs, vids, books and manuals into a cohesive, updated whole would be a god send! -- Douglas E Knapp Creative Commons Film Group, Helping people make open source movies with open source software! http://douglas.bespin.org/CommonsFilmGroup/phpBB3/index.php Massage in Gelsenkirchen-Buer: http://douglas.bespin.org/tcm/ztab1.htm Please link to me and trade links with me! Open Source Sci-Fi mmoRPG Game project. http://sf-journey-creations.wikispot.org/Front_Page http://code.google.com/p/perspectiveproject/ ___ Bf-committers mailing list Bf-committers@blender.org http://lists.blender.org/mailman/listinfo/bf-committers
Re: [Bf-committers] Including documentation in BCon cycle
Hi, On 11/08/2011 03:18 PM, Knapp wrote: Maybe it's time to hire someone to get a well documented wiki ;) Funny, I was thinking the same thing as I fell asleep last night. One person in charge of finding the problems and talking with the devs, coordinating of the writers and pulling together all the docs, what you are saying above is OK for the wiki. As it's being discussed in docboard and #blenderwiki: * we're now reviewing the 2.5 manual (not in good shape at all) * we'll install a reviewing system * we'll define a team of reviewers with the rights to accept edits made in wiki, so that the content users will see is always ok * for each blender module (modeling, rigging, etc), we intend to find a 'main' (not exclusive) reviewer that will take care of: * review and and format contents inserted by devs * review content inserted by occasional editors * hunt for new editors (experienced in blender possibly) * these modules reviewers will have to communicate with the main admins (more on this later) to make sure the manual structure/templates/etc are agreed upon. This should be a team work. Though, IMO the first input should come by the developer, which should write even just a draft (no wiki formatting) the tool documentation. Otherwise you get the current problems, also outlined by Francesco. The potential writer has to discover the tool by trial and error, then find the strength to formalize what he has discovered, format it in good wikitext, using blenderwiki templates. Honestly, that's a lot to ask. links, blogs, vids, books and manuals into a cohesive, updated whole would be a god send! I think this is not a good idea. Two examples: * deadlinks are a nigthmare to maintain * you can't paste a book or a blog page in the wiki without permission IMHO The wiki should not phagocytize the whole web, but rather be a good reference with its own identity and direction. We should not trash everything in, but rather make a good team work, and refine communication channels: devs - wiki admins - writers team - users, also formalizing this in the BCon, so that documentation is not an boring optional, but part of the job of the developer. Surely with insights from devs the doc will become much more appealing also to professional users and companies :) Regards, Luca _ http://wiki.blender.org/index.php/User:Mindrones http://www.mindrones.com ___ Bf-committers mailing list Bf-committers@blender.org http://lists.blender.org/mailman/listinfo/bf-committers
Re: [Bf-committers] Including documentation in BCon cycle
On Tue, Nov 8, 2011 at 1:32 PM, Knapp magick.c...@gmail.com wrote: On Tue, Nov 8, 2011 at 3:52 PM, mindrones mindro...@gmail.com wrote: Hi, On 11/08/2011 03:18 PM, Knapp wrote: Maybe it's time to hire someone to get a well documented wiki ;) Funny, I was thinking the same thing as I fell asleep last night. One person in charge of finding the problems and talking with the devs, coordinating of the writers and pulling together all the docs, what you are saying above is OK for the wiki. As it's being discussed in docboard and #blenderwiki: * we're now reviewing the 2.5 manual (not in good shape at all) That is for sure. One of the reasons I really liked Blender was the 2.4 manual. It was great. I wonder why? * we'll install a reviewing system * we'll define a team of reviewers with the rights to accept edits made in wiki, so that the content users will see is always ok * for each blender module (modeling, rigging, etc), we intend to find a 'main' (not exclusive) reviewer that will take care of: * review and and format contents inserted by devs * review content inserted by occasional editors * hunt for new editors (experienced in blender possibly) * these modules reviewers will have to communicate with the main admins (more on this later) to make sure the manual structure/templates/etc are agreed upon. This should be a team work. Though, IMO the first input should come by the developer, which should write even just a draft (no wiki formatting) the tool documentation. Otherwise you get the current problems, also outlined by Francesco. The potential writer has to discover the tool by trial and error, then find the strength to formalize what he has discovered, format it in good wikitext, using blenderwiki templates. Honestly, that's a lot to ask. Ya but at the same time lots of us do 30-90 minute vids. links, blogs, vids, books and manuals into a cohesive, updated whole would be a god send! I think this is not a good idea. Two examples: * deadlinks are a nigthmare to maintain Yes, but they are all OK on Wikipedia and could be here too with the right set up. * you can't paste a book or a blog page in the wiki without permission Clearly a push not pull situation. I think authors and bloggers would be happy to try and keep a link page up to date if they knew it was there and the users knew it was the first place to stop when looking for something. Blender.org should be the first or second place (behind Google) that users go for their info. As it stands, it is about the last place I go but it used to be the first. On the other hand we already have the books. Did you know that? I know it took me a long time to find them when I knew they were there! These are some great sources of info! They SHOULD be very easy to find with Google but they are not. http://wiki.blender.org/index.php/Doc:2.5/Books http://wiki.blender.org/index.php/Doc:2.4/Books IMHO The wiki should not phagocytize the whole web, but rather be a good reference with its own identity and direction. I think we should keep in mind that we have a manual and it should be THE source of good info and then we have a wiki. (I know the two overlap) We should not trash everything in, but rather make a good team work, and refine communication channels: devs - wiki admins - writers team - users, also formalizing this in the BCon, so that documentation is not an boring optional, but part of the job of the developer. I have long thought that documentors should be recognized for what they do just as devs are. I truly can't say a dev is more important than a doccer in a mature program like blender. The program lives and dies based on both sides of the work. Surely with insights from devs the doc will become much more appealing also to professional users and companies :) The biggest problem that I see with blender is the new user coming to blender and that leaving because they are so over loaded and can't find good help or docs. God knows we have a great program but without good intros newbies will leave. I got over this hump because of graybeards vids on the gui. I can't wait to do my first ship sailing on the open seas with cycles rendering of the animation! And think of the blood effects you could do with dynamic paint! On the other hand what do I use for water? There are now like 6 ways to do it! LOL. I can just see dynamic paint particles impacting the top of my sea and spreading out in ripples with my old time ship reflecting in the water! I would love to know how you do grass in Cycles! :-) Regards, Luca True. I have told friends about Blender, and many gave up after a day or two because of frustration from above reasons. -- Douglas E Knapp Creative Commons Film Group, Helping people make open source movies with open source software!
Re: [Bf-committers] Including documentation in BCon cycle
I must agree that the documentation is way behind where it should be. Maybe LetterRip's plan for Google winter of documentation could help there? ___ Bf-committers mailing list Bf-committers@blender.org http://lists.blender.org/mailman/listinfo/bf-committers
Re: [Bf-committers] Including documentation in BCon cycle
Hey all, quick note: I started this thread because I wanted to discuss specifically about developers involvement in the documentation of the stuff they code. Thoughts and ideas about the documentation in general should be sent to the docboard mailing list, not here. Not answering is ok (it is an answer by itself after all :P ), while losing focus can be quite a waste of time! Regards, Luca _ http://wiki.blender.org/index.php/User:Mindrones http://www.mindrones.com ___ Bf-committers mailing list Bf-committers@blender.org http://lists.blender.org/mailman/listinfo/bf-committers
Re: [Bf-committers] Including documentation in BCon cycle
I very much agree with the thrust of Luca's email. Though, I'd suggest this: rather than postpone a full release to wait for documentation, treat a lack of documentation in a new feature as a bug. If that bug is not squashed, the feature cannot be included in trunk for the current release cycle. -Jason mindrones mindro...@gmail.com wrote: Hi all, Bastien and I are in the middle of reviewing the 2.5 manual and, sadly, it's not in a good shape, really. A complete report will follow in docboard mailing list. We'll work to grow the wiki team but really, I think it's time to rethink a bit about the documentation, especially adopting a 2 months BCon cycle. I'd like to propose a very simple way to get stuff documented. ¦¦ ¦ Documentation phase should be included in the release cycle. ¦ ¦¦ Ref: http://wiki.blender.org/index.php/Dev:Doc/Process/Release_Cycle In other words I'm saying: --- ¦ ¦ ¦ No documentation in wiki - No release. ¦ ¦ ¦ --- We have discussed this in irc a bit and many (would) agree, and it was a hot topic at the Blender Conference too as far as I know. Really, having faster release cycles is all good, but it has to take in account documentation too, otherwise users will get pissed off after 5 releases in a year and no decent docs. And even if users are happy like this (which I doubt), I think it's a waste having such beautiful tools undocumented: I'm sure a great part of the developer work won't be used at all, which is a shame :) IMHO the documentation has to start from the developer, not from users. -- A couple of proposals to make the developers life easier on wiki docs. 1) Informal chats --- The dev explains the tool he has developed in an informal chat with the documenter, which puts the info he gets in wiki nicely. 2) Unformatted docs from devs --- Since many suffer the mediawiki syntax, it would be ok even if the developer types pure text in a wiki page, not formatted as wikitext. Writers would then help formatting, beautifying, adding tutorials, images, examples, etc. -- Any feedback is welcome :) Regards, Luca http://wiki.blender.org/index.php/User:Mindrones http://www.mindrones.com ___ Bf-committers mailing list Bf-committers@blender.org http://lists.blender.org/mailman/listinfo/bf-committers ___ Bf-committers mailing list Bf-committers@blender.org http://lists.blender.org/mailman/listinfo/bf-committers
Re: [Bf-committers] Including documentation in BCon cycle
¦ ¦ ¦ Documentation phase should be included in the release cycle. ¦ ¦ ¦ Ref: http://wiki.blender.org/index.php/Dev:Doc/Process/Release_Cycle In other words I'm saying: --- ¦ ¦ ¦ No documentation in wiki - No release. ¦ ¦ ¦ --- I love the idea but it needs a lot of limits. First, I want to see things released as soon as they are done. I don't want to see dev productivity negatively impacted by them being forced to wait because they did not write a book about their code. I do tutorials and I often do them on very little solid info. I get that info by asking on IRC or reading release notes, emails here, or the devs blogs. So, not releasing until the docs are there is a lot like not releasing until the the code is bug free. A good judgement call is needed about what is enough doc before the code is OKed for release. I think the rule should be that the code should have at least minimal documentation. IE I just made a new thing called grease pen. You turn it on with xxx and you have features x,y,z and it is intended to help collaboration between artist by drawing on the work screen. Something this simple is a great help in jump starting the advanced users to learn and then write more docs. A contact email is of great help so we can ask about details that we do not understand. Naturally the dev writing great docs or making a video is better but devs should use their time to write code and not extensive newbie directed docs. Currently a bigger problem is finding the docs and films that are relevant to the newest version and not something that is 10 years old. The last big update to the manual greatly helped but their is still a problem on the WWW and Google searches. Tracking the state of documentation for each part might be of great help. Perhaps some sort of rating from 0= no docs to 10 great professionally written docs. Then writers could search out functions or features that need documentation more easily. I often wonder what tut film I should do next, something like this would help me know what really needed the most work. -- Douglas E Knapp Creative Commons Film Group, Helping people make open source movies with open source software! http://douglas.bespin.org/CommonsFilmGroup/phpBB3/index.php Massage in Gelsenkirchen-Buer: http://douglas.bespin.org/tcm/ztab1.htm Please link to me and trade links with me! Open Source Sci-Fi mmoRPG Game project. http://sf-journey-creations.wikispot.org/Front_Page http://code.google.com/p/perspectiveproject/ ___ Bf-committers mailing list Bf-committers@blender.org http://lists.blender.org/mailman/listinfo/bf-committers
Re: [Bf-committers] Including documentation in BCon cycle
I'm not a developer so I see your suggestion from an artist point of view: It's an incredile pain try to figure out how a tool works! Really, I think here in our studio we spent dozen of hours in testing, defining our own ideas of what is done by a tool without really know if what we imagine is true. And this in many situation lands to not use that tool but just find another way to do something that works! I agree in the relationship: No docs = not ready for trunk Maybe it's time to hire someone to get a well documented wiki ;) E-Mail Sent via BlackBerry from BT Mobile -Original Message- From: mindrones mindro...@gmail.com Sender: bf-committers-boun...@blender.org Date: Sun, 06 Nov 2011 22:04:29 To: bf-blender developersbf-committers@blender.org Reply-To: bf-blender developers bf-committers@blender.org Subject: [Bf-committers] Including documentation in BCon cycle Hi all, Bastien and I are in the middle of reviewing the 2.5 manual and, sadly, it's not in a good shape, really. A complete report will follow in docboard mailing list. We'll work to grow the wiki team but really, I think it's time to rethink a bit about the documentation, especially adopting a 2 months BCon cycle. I'd like to propose a very simple way to get stuff documented. ¦¦ ¦ Documentation phase should be included in the release cycle. ¦ ¦¦ Ref: http://wiki.blender.org/index.php/Dev:Doc/Process/Release_Cycle In other words I'm saying: --- ¦ ¦ ¦ No documentation in wiki - No release. ¦ ¦ ¦ --- We have discussed this in irc a bit and many (would) agree, and it was a hot topic at the Blender Conference too as far as I know. Really, having faster release cycles is all good, but it has to take in account documentation too, otherwise users will get pissed off after 5 releases in a year and no decent docs. And even if users are happy like this (which I doubt), I think it's a waste having such beautiful tools undocumented: I'm sure a great part of the developer work won't be used at all, which is a shame :) IMHO the documentation has to start from the developer, not from users. -- A couple of proposals to make the developers life easier on wiki docs. 1) Informal chats --- The dev explains the tool he has developed in an informal chat with the documenter, which puts the info he gets in wiki nicely. 2) Unformatted docs from devs --- Since many suffer the mediawiki syntax, it would be ok even if the developer types pure text in a wiki page, not formatted as wikitext. Writers would then help formatting, beautifying, adding tutorials, images, examples, etc. -- Any feedback is welcome :) Regards, Luca http://wiki.blender.org/index.php/User:Mindrones http://www.mindrones.com ___ Bf-committers mailing list Bf-committers@blender.org http://lists.blender.org/mailman/listinfo/bf-committers ___ Bf-committers mailing list Bf-committers@blender.org http://lists.blender.org/mailman/listinfo/bf-committers
[Bf-committers] Including documentation in BCon cycle
Hi all, Bastien and I are in the middle of reviewing the 2.5 manual and, sadly, it's not in a good shape, really. A complete report will follow in docboard mailing list. We'll work to grow the wiki team but really, I think it's time to rethink a bit about the documentation, especially adopting a 2 months BCon cycle. I'd like to propose a very simple way to get stuff documented. ¦¦ ¦ Documentation phase should be included in the release cycle. ¦ ¦¦ Ref: http://wiki.blender.org/index.php/Dev:Doc/Process/Release_Cycle In other words I'm saying: --- ¦ ¦ ¦ No documentation in wiki - No release. ¦ ¦ ¦ --- We have discussed this in irc a bit and many (would) agree, and it was a hot topic at the Blender Conference too as far as I know. Really, having faster release cycles is all good, but it has to take in account documentation too, otherwise users will get pissed off after 5 releases in a year and no decent docs. And even if users are happy like this (which I doubt), I think it's a waste having such beautiful tools undocumented: I'm sure a great part of the developer work won't be used at all, which is a shame :) IMHO the documentation has to start from the developer, not from users. -- A couple of proposals to make the developers life easier on wiki docs. 1) Informal chats --- The dev explains the tool he has developed in an informal chat with the documenter, which puts the info he gets in wiki nicely. 2) Unformatted docs from devs --- Since many suffer the mediawiki syntax, it would be ok even if the developer types pure text in a wiki page, not formatted as wikitext. Writers would then help formatting, beautifying, adding tutorials, images, examples, etc. -- Any feedback is welcome :) Regards, Luca http://wiki.blender.org/index.php/User:Mindrones http://www.mindrones.com ___ Bf-committers mailing list Bf-committers@blender.org http://lists.blender.org/mailman/listinfo/bf-committers
