<div dir="ltr">Hi !<br><div><br></div><div>Here is Ivan Paulos T.<br></div><div><br>Here is my 2 cents. <br><br>I know, I know, I'm now located at the <br>"Obsolete pieces of Blender junkyard of the obsolete wiki writers..."<br><br>I'm reading the contents of this discussion, but we have made it in the past <br></div><div>several times. <br><br>I was working on a project called BTSC since 2011, <br></div><div>but so far, I have no financial help to continue, not even a single<br></div><div>word as "Thank you", or "Can we start a real discussion about your project ?".<br></div><div><br></div><div>I'm seeing those discussions as redundant, and it seems to me that the <br></div><div>move to the Sphinx may help with what BTSC was made to be, <br>but BTSC was made to use Wigit instead. When I was working, <br></div><div>I was setting up a framework, not a simple "another wiki project". <br></div><div><br></div><div>Now I'm working for another company, and the project was frozen in <br></div><div>August 2014. I have nearly financially broken, and I was really trying to help, <br>but so far, I have discovered that some friends here (in Brazil) are even against BTSC. <br><br>I was about to say that was for no reason, but the reason was mostly <br></div><div>related to politics and the ego life of disputed 'positions'.<br><br></div><div>If you're willing to solve the manual problem, you will have to start with the reference, <br></div><div>but most people are willing a "simple big tutorial", but you will have to fix the <br></div><div>references prior to everything. This will need time to fix.<br></div><div><br>In my opinion, the .rst files are good for one thing:<br></div><div>"Extended tooltips that you can download with or without Blender", but a<br></div><div>manual with a didactic line needs to start fixing "References" prior to work <br></div><div>on the "User Manual", and after, you can 'tesselate' the whole thing.<br></div><div><br></div><div>Another great tip is that in general, writers and translators are considered <br>a problem in free software by some coders, and some of them are even <br>considered a second level people. And they are, in general, forced to <br></div><div>adapt themselves to every situation that the coders decide that they have to, <br></div><div>without a real 'voice' at the decisions. <br></div><div><br></div><div>Some of them are even talented enough to become good coders, mainly <br>because for big projects, you will need to understand what 'organization' means, <br>but the free software looses a lot of writers everyday, and the consequences are obvious:<br><br></div><div>Bad documentation and coders loosing 'faith' in the free software ecosystem.<br></div><br>Sorry for the long e-mail. <br>Cheers ! <br><div></div><div><br></div></div><div class="gmail_extra"><br><div class="gmail_quote">2015-01-15 9:00 GMT-02:00 <span dir="ltr"><<a href="mailto:bf-docboard-request@blender.org" target="_blank">bf-docboard-request@blender.org</a>></span>:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Send Bf-docboard mailing list submissions to<br>
<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a><br>
<br>
To subscribe or unsubscribe via the World Wide Web, visit<br>
<a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
or, via email, send a message with subject or body 'help' to<br>
<a href="mailto:bf-docboard-request@blender.org">bf-docboard-request@blender.org</a><br>
<br>
You can reach the person managing the list at<br>
<a href="mailto:bf-docboard-owner@blender.org">bf-docboard-owner@blender.org</a><br>
<br>
When replying, please edit your Subject line so it is more specific<br>
than "Re: Contents of Bf-docboard digest..."<br>
<br>
<br>
Today's Topics:<br>
<br>
1. Re: Being involved In documentation (Abuelo S. B. Chdancer)<br>
2. On types of manual we want (Abuelo S. B. Chdancer)<br>
3. Re: Being involved In documentation (Campbell Barton)<br>
4. Re: Being involved In documentation (Campbell Barton)<br>
5. What has been done so far.... (Abuelo S. B. Chdancer)<br>
6. Re: What has been done so far.... (Campbell Barton)<br>
7. Re: What has been done so far.... (Abuelo S. B. Chdancer)<br>
8. Specific plans and discussion of what our manual should be<br>
and how to get it (Abuelo S. B. Chdancer)<br>
9. Re: Specific plans and discussion of what our manual should<br>
be and how to get it (brita)<br>
10. Re: Specific plans and discussion of what our manual should<br>
be and how to get it (Greg Zaal)<br>
11. Re: Being involved In documentation (Pep Ribal)<br>
<br>
<br>
----------------------------------------------------------------------<br>
<br>
Message: 1<br>
Date: Wed, 14 Jan 2015 13:54:36 +0100<br>
From: "Abuelo S. B. Chdancer" <<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>><br>
Subject: Re: [Bf-docboard] Being involved In documentation<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID:<br>
<<a href="mailto:CAFH9JFOq73hQPLjmTjidQwvdgvEY1Pi%2B7_ofJxzbCHkXc1Pozg@mail.gmail.com">CAFH9JFOq73hQPLjmTjidQwvdgvEY1Pi+7_ofJxzbCHkXc1Pozg@mail.gmail.com</a>><br>
Content-Type: text/plain; charset="utf-8"<br>
<br>
In reply to Pep Ribal....<br>
<br>
Absolutely. The surprise is that some of what you suggest has been done,<br>
but who would know? There are people who are listed as being in charge of<br>
bits of the manual, the list is somewhere on some server, I have forgotten<br>
where.<br>
<br>
It is an odd fact that more people want to code than explain the code. This<br>
has been the case in the computer industry for decades and the lousy level<br>
of most manuals is the result. My new hard disk drive comes with a manual<br>
that warns not to connect the drive when the computer is on. How do you<br>
read this manual? - It's in pdf format on the drive. (Anyone notice a<br>
problem with this?)<br>
<br>
I will circulate some guidelines for discussion....<br>
<br>
On 14 January 2015 at 07:12, Pep Ribal <<a href="mailto:pepribal@gmail.com">pepribal@gmail.com</a>> wrote:<br>
<br>
> Hi all,<br>
><br>
> I understand the disappointment that the new documentation system has<br>
> caused. I also think that it builds a big barrier for the people who want<br>
> to help with documentation writing. It's true that the wiki made it much<br>
> more simple to help, but I agree with Campbell that even the simplicity of<br>
> the wiki didn't motivate people enough. And that means that technology was<br>
> not the problem. I think the technology (wiki) was the right one to use,<br>
> but the project lacked (and still lacks) something more.<br>
><br>
> The key question is: why isn't people motivated? For instance, Blender<br>
> development has a huge entry barrier, compared to wiki, and even compared<br>
> to the new reST-SVN system. However, activity is way bigger in development<br>
> than in documentation. One does not expect that a project as big as Blender<br>
> is suffering from a extremely low documentation development pace.<br>
><br>
> I've been working with Blender since many years ago, but I was away from<br>
> it for a while. Now that I'm back, I see the same eternal problem that was<br>
> present before: documentation is the worst of Blender, by far. And I don't<br>
> see it changing any time soon, unless something is done. And I don't think<br>
> a change in technology is the response (and even less a change that raises<br>
> the entry barrier).<br>
><br>
> Motivation is the key. But how we manage to motivate people to contribute<br>
> to the docs?<br>
><br>
> I think that some Project Management skills should be poured in. A<br>
> "project manager" should be appointed. A few key positions should be filled<br>
> (official writers), and an official documentation team should be set up. If<br>
> we have a team of developers, an official team, with a clear coordinator<br>
> and a clear team of key developers, each one responsible for his module,<br>
> why not have the same for documenters? That's what the documentation<br>
> project lacks. There is no official team. So there is not a feeling of<br>
> "important department".<br>
><br>
> Why do we need an official team? Because there's no more motivating thing<br>
> than feeling officially part of something. In this case, the ?official<br>
> Blender documentation team?. And not only feeling that, but also seeing it,<br>
> for instance, in the appropriate page in Blender website: names and<br>
> functions of every ?official? member of that team. I think that would<br>
> attract writers.<br>
><br>
> But it shouldn't only be a list of names in a web page. Being part of the<br>
> team should offer additional ?privileges?. The more of them we can give,<br>
> the more motivation writers will have.<br>
><br>
> What should be offered to writers besides credit? I think one of the most<br>
> important things is attention from the developer responsible for the<br>
> documented module. This is a crucial part in all this.<br>
><br>
> Perhaps other things could be offered, but as a start, these couple of<br>
> things would help enough, I think.<br>
><br>
> Regards,<br>
><br>
> Pep.<br>
><br>
> El 14/01/15 a las 08:33, Abuelo S. B. Chdancer escribi?:<br>
><br>
> Hi to Nkansah Rexford,<br>
><br>
> A contributor should be able to go to a normal webpage.<br>
><br>
> Register what he would be interested in doing.<br>
><br>
> Be contacted by a real human who agrees the task.<br>
><br>
> The writer should be able to submit using email or a simple web based<br>
> upload form. For the text.<br>
><br>
> If approved by an editor or by peer review the more complicated task of<br>
> adding illustrations can be handle by some method.<br>
><br>
><br>
><br>
> On 14 January 2015 at 00:47, Nkansah Rexford <<a href="mailto:nkansahrexford@gmail.com">nkansahrexford@gmail.com</a>><br>
> wrote:<br>
><br>
>> Hello Chdancer,<br>
>><br>
>> I think you have a point, and its from a user who's got no idea what<br>
>> those terms are.<br>
>><br>
>> However, look at it this way too. Trying to explain every single detail<br>
>> of the steps will require another documentation on its own. "What repo<br>
>> is?", "How to clone", "What is reST?", svn (what is even version control?<br>
>> duh!), checkout (what am I buying?), pip, requirements.txt and so on.<br>
>><br>
>> Those are stuffs with detailed documentations on their own found<br>
>> everywhere on the net. I don't think the getting started page on Blender<br>
>> should aggregate all these information and present it to anyone who<br>
>> actually wants to get started (beside's that'll be aggregating<br>
>> documentations into a documentation).<br>
>><br>
>> Of course, more flesh can (and likely will) be added to those getting<br>
>> started pages, but remember not *everything *can be covered or all the<br>
>> terminologies can be expounded.<br>
>><br>
>> I think explaining every single thing on that page defeats the whole<br>
>> idea of 'getting started'. Its not a training course. Its to get you<br>
>> started, so they're pointers, offering guidance as to how to go about it.<br>
>><br>
>> Therefore, I think as someone who really wants to get started, doing a<br>
>> bit more googling and reading outside the getting started page should make<br>
>> things happen much easier, for both authors of get started pages and also<br>
>> the 'get-startee' (bad english, but hope you get it)<br>
>><br>
>> I know its hard to understand pages like that, but I hope it gets<br>
>> improved to the best possible to bridge the gap between devs and users.<br>
>><br>
>> rex<br>
>><br>
>> On Tuesday, January 13, 2015, Abuelo S. B. Chdancer <<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>><br>
>> wrote:<br>
>><br>
>>> Campbell Barton reminded...<br>
>>><br>
>>> "While this is subjective, we have had contributions submitted via our<br>
>>> project page:<br>
>>><br>
>>> <a href="https://developer.blender.org/tag/documentation/" target="_blank">https://developer.blender.org/tag/documentation/</a> "<br>
>>><br>
>>><br>
>>> Guys, someone who USES Blender may not know the first thing about<br>
>>> coding, someone who can write simple prose explaining to another person in<br>
>>> clear language how to DO something artistic may be totally useless when it<br>
>>> comes to installing software or plugging in a USB plug.<br>
>>><br>
>>> I bet a lot of possible contributors give up when they read this....<br>
>>><br>
>>> "We have migrated the content over to reST format, so that the manual<br>
>>> can be built with Sphinx. A good amount of work is still required to<br>
>>> complete the migration (learn more about the open tasks in Phabricator).<br>
>>><br>
>>> If you want to start contributing or want to have a look at the new<br>
>>> manual, here we have some instructions.<br>
>>> How to build the docs locally<br>
>>><br>
>>> - Checkout the Subversion repository svn checkout<br>
>>> <a href="https://svn.blender.org/svnroot/bf-manual/trunk" target="_blank">https://svn.blender.org/svnroot/bf-manual/trunk</a><br>
>>> - Move to the location where the repo was cloned<br>
>>> - Run pip install -r requirements.txt (Windows user make sure you<br>
>>> are using Python 2.7, not 3.x)<br>
>>> - Build a section of the manual (for example make render)<br>
>>> - Launch the contents_quicky.html inside of the html folder and<br>
>>> browse the freshly build render docs<br>
>>><br>
>>><br>
>>> That is a hundred times worse than trying to use the wiki manual. It<br>
>>> is mindboggingly offputting and not just incomprehensible but presents such<br>
>>> a hurdle that most people will stop at that point and forget being involved.<br>
>>><br>
>>> What it should say is.....<br>
>>><br>
>>> Read this (hopefully well written and elegantly presented) webpage<br>
>>> which explains how you register what you would like to do.<br>
>>><br>
>>> If worried about 'no nothings' writing drivel, that is why we invented<br>
>>> human editors. Also it is technically possible to have peer reviews of<br>
>>> submitted entries prior to making the entry official.<br>
>>><br>
>>> I was in the middle of working on my latest animation.....<br>
>>><br>
>>><br>
>>><br>
>>><br>
>><br>
>> --<br>
>> +Rexford <<a href="http://google.com/+Nkansahrexford" target="_blank">http://google.com/+Nkansahrexford</a>> | Africa Center<br>
>> <<a href="http://africacenter.net" target="_blank">http://africacenter.net</a>> | WiR<br>
>> <<a href="https://outreach.wikimedia.org/wiki/Wikipedian_in_Residence" target="_blank">https://outreach.wikimedia.org/wiki/Wikipedian_in_Residence</a>> |<br>
>> WikiAfrica <<a href="http://wikiafrica.net" target="_blank">http://wikiafrica.net</a>> | User:Nkansahrexford<br>
>> <<a href="http://en.wikipedia.org/wiki/User:Nkansahrexford" target="_blank">http://en.wikipedia.org/wiki/User:Nkansahrexford</a>><br>
>><br>
>><br>
>> _______________________________________________<br>
>> Bf-docboard mailing list<br>
>> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
>> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
>><br>
>><br>
><br>
><br>
> _______________________________________________<br>
> Bf-docboard mailing listBf-docboard@blender.orghttp://<a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">lists.blender.org/mailman/listinfo/bf-docboard</a><br>
><br>
><br>
><br>
> _______________________________________________<br>
> Bf-docboard mailing list<br>
> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
><br>
><br>
-------------- next part --------------<br>
An HTML attachment was scrubbed...<br>
URL: <a href="http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/d0d81c48/attachment.html" target="_blank">http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/d0d81c48/attachment.html</a><br>
<br>
------------------------------<br>
<br>
Message: 2<br>
Date: Wed, 14 Jan 2015 14:05:03 +0100<br>
From: "Abuelo S. B. Chdancer" <<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>><br>
Subject: [Bf-docboard] On types of manual we want<br>
To: Blender Documentation Project <<a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a>><br>
Message-ID:<br>
<<a href="mailto:CAFH9JFPXkSx8z0EZkQpqzqqvoBr_4RaGgtwL1_VvDApzsMUwXQ@mail.gmail.com">CAFH9JFPXkSx8z0EZkQpqzqqvoBr_4RaGgtwL1_VvDApzsMUwXQ@mail.gmail.com</a>><br>
Content-Type: text/plain; charset="utf-8"<br>
<br>
Please let me know which of these types of manual appeal, or give examples<br>
of on-line manuals that you have used for other software that you think are<br>
high quality manuals, or what ideas you have about how a manual should be<br>
(NOT what software version it runs on or what device it should be<br>
compatible with)<br>
<br>
Do you want a quick reference to remind how to use a command?<br>
<br>
Do you want a simple English explanation of not just what it does but why<br>
you use it?<br>
<br>
Do you want a topic based manual - what things can be done, which commands<br>
are relevant.<br>
<br>
Do you want a teaching manual - (tutorials)<br>
<br>
Please voice what you want from a manual, because if you don't you'll get a<br>
massive glob of goo.<br>
<br>
Also - what manual or source do you normally turn to when hitting a<br>
problem with Blender.<br>
<br>
Also- what did you use to learn Blender?<br>
<br>
Also - what were (are) the biggest hurdles in learning Blender<br>
-------------- next part --------------<br>
An HTML attachment was scrubbed...<br>
URL: <a href="http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/4b3dd31d/attachment-0001.htm" target="_blank">http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/4b3dd31d/attachment-0001.htm</a><br>
<br>
------------------------------<br>
<br>
Message: 3<br>
Date: Thu, 15 Jan 2015 00:19:15 +1100<br>
From: Campbell Barton <<a href="mailto:ideasman42@gmail.com">ideasman42@gmail.com</a>><br>
Subject: Re: [Bf-docboard] Being involved In documentation<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID:<br>
<CAEcf3NyyVZoiorLgiPR7OZQeq7srtor5C-DOz=<a href="mailto:FeTu-H-kcOAA@mail.gmail.com">FeTu-H-kcOAA@mail.gmail.com</a>><br>
Content-Type: text/plain; charset=UTF-8<br>
<br>
On Wed, Jan 14, 2015 at 5:12 PM, Pep Ribal <<a href="mailto:pepribal@gmail.com">pepribal@gmail.com</a>> wrote:<br>
> Hi all,<br>
><br>
> I understand the disappointment that the new documentation system has<br>
> caused. I also think that it builds a big barrier for the people who want to<br>
> help with documentation writing. It's true that the wiki made it much more<br>
> simple to help, but I agree with Campbell that even the simplicity of the<br>
> wiki didn't motivate people enough. And that means that technology was not<br>
> the problem. I think the technology (wiki) was the right one to use, but the<br>
> project lacked (and still lacks) something more.<br>
<br>
Yes, its quite possible that the issue we face is todo with getting<br>
active contributors, no matter which technology we use.<br>
<br>
> The key question is: why isn't people motivated? For instance, Blender<br>
> development has a huge entry barrier, compared to wiki, and even compared to<br>
> the new reST-SVN system. However, activity is way bigger in development than<br>
> in documentation. One does not expect that a project as big as Blender is<br>
> suffering from a extremely low documentation development pace.<br>
<br>
Mailed on this topic a while back,<br>
<a href="http://lists.blender.org/pipermail/bf-docboard/2014-May/004459.html" target="_blank">http://lists.blender.org/pipermail/bf-docboard/2014-May/004459.html</a><br>
<br>
<br>
> I've been working with Blender since many years ago, but I was away from it<br>
> for a while. Now that I'm back, I see the same eternal problem that was<br>
> present before: documentation is the worst of Blender, by far. And I don't<br>
> see it changing any time soon, unless something is done. And I don't think a<br>
> change in technology is the response (and even less a change that raises the<br>
> entry barrier).<br>
><br>
> Motivation is the key. But how we manage to motivate people to contribute to<br>
> the docs?<br>
><br>
> I think that some Project Management skills should be poured in. A "project<br>
> manager" should be appointed. A few key positions should be filled (official<br>
> writers), and an official documentation team should be set up. If we have a<br>
> team of developers, an official team, with a clear coordinator and a clear<br>
> team of key developers, each one responsible for his module, why not have<br>
> the same for documenters? That's what the documentation project lacks. There<br>
> is no official team. So there is not a feeling of "important department".<br>
<br>
Agree, but we need someone who is naturally good in the role of<br>
helping people work together, not just someone who comes in and says<br>
they will tell others what to do.<br>
<br>
> Why do we need an official team? Because there's no more motivating thing<br>
> than feeling officially part of something. In this case, the ?official<br>
> Blender documentation team?. And not only feeling that, but also seeing it,<br>
> for instance, in the appropriate page in Blender website: names and<br>
> functions of every ?official? member of that team. I think that would<br>
> attract writers.<br>
><br>
> But it shouldn't only be a list of names in a web page. Being part of the<br>
> team should offer additional ?privileges?. The more of them we can give, the<br>
> more motivation writers will have.<br>
><br>
> What should be offered to writers besides credit? I think one of the most<br>
> important things is attention from the developer responsible for the<br>
> documented module. This is a crucial part in all this.<br>
<br>
Agree connecting writers with devs is important, ideally having new<br>
features in blender be documented in so devs & writers collaborate.<br>
<br>
> Perhaps other things could be offered, but as a start, these couple of<br>
> things would help enough, I think.<br>
><br>
> Regards,<br>
><br>
> Pep.<br>
><br>
> El 14/01/15 a las 08:33, Abuelo S. B. Chdancer escribi?:<br>
><br>
> Hi to Nkansah Rexford,<br>
><br>
> A contributor should be able to go to a normal webpage.<br>
><br>
> Register what he would be interested in doing.<br>
><br>
> Be contacted by a real human who agrees the task.<br>
><br>
> The writer should be able to submit using email or a simple web based upload<br>
> form. For the text.<br>
><br>
> If approved by an editor or by peer review the more complicated task of<br>
> adding illustrations can be handle by some method.<br>
><br>
><br>
><br>
> On 14 January 2015 at 00:47, Nkansah Rexford <<a href="mailto:nkansahrexford@gmail.com">nkansahrexford@gmail.com</a>><br>
> wrote:<br>
>><br>
>> Hello Chdancer,<br>
>><br>
>> I think you have a point, and its from a user who's got no idea what those<br>
>> terms are.<br>
>><br>
>> However, look at it this way too. Trying to explain every single detail of<br>
>> the steps will require another documentation on its own. "What repo is?",<br>
>> "How to clone", "What is reST?", svn (what is even version control? duh!),<br>
>> checkout (what am I buying?), pip, requirements.txt and so on.<br>
>><br>
>> Those are stuffs with detailed documentations on their own found<br>
>> everywhere on the net. I don't think the getting started page on Blender<br>
>> should aggregate all these information and present it to anyone who actually<br>
>> wants to get started (beside's that'll be aggregating documentations into a<br>
>> documentation).<br>
>><br>
>> Of course, more flesh can (and likely will) be added to those getting<br>
>> started pages, but remember not everything can be covered or all the<br>
>> terminologies can be expounded.<br>
>><br>
>> I think explaining every single thing on that page defeats the whole idea<br>
>> of 'getting started'. Its not a training course. Its to get you started, so<br>
>> they're pointers, offering guidance as to how to go about it.<br>
>><br>
>> Therefore, I think as someone who really wants to get started, doing a bit<br>
>> more googling and reading outside the getting started page should make<br>
>> things happen much easier, for both authors of get started pages and also<br>
>> the 'get-startee' (bad english, but hope you get it)<br>
>><br>
>> I know its hard to understand pages like that, but I hope it gets improved<br>
>> to the best possible to bridge the gap between devs and users.<br>
>><br>
>> rex<br>
>><br>
>> On Tuesday, January 13, 2015, Abuelo S. B. Chdancer <<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>><br>
>> wrote:<br>
>>><br>
>>> Campbell Barton reminded...<br>
>>><br>
>>> "While this is subjective, we have had contributions submitted via our<br>
>>> project page:<br>
>>><br>
>>> <a href="https://developer.blender.org/tag/documentation/" target="_blank">https://developer.blender.org/tag/documentation/</a> "<br>
>>><br>
>>><br>
>>> Guys, someone who USES Blender may not know the first thing about coding,<br>
>>> someone who can write simple prose explaining to another person in clear<br>
>>> language how to DO something artistic may be totally useless when it comes<br>
>>> to installing software or plugging in a USB plug.<br>
>>><br>
>>> I bet a lot of possible contributors give up when they read this....<br>
>>><br>
>>> "We have migrated the content over to reST format, so that the manual can<br>
>>> be built with Sphinx. A good amount of work is still required to complete<br>
>>> the migration (learn more about the open tasks in Phabricator).<br>
>>><br>
>>> If you want to start contributing or want to have a look at the new<br>
>>> manual, here we have some instructions.<br>
>>><br>
>>> How to build the docs locally<br>
>>><br>
>>> Checkout the Subversion repository svn checkout<br>
>>> <a href="https://svn.blender.org/svnroot/bf-manual/trunk" target="_blank">https://svn.blender.org/svnroot/bf-manual/trunk</a><br>
>>> Move to the location where the repo was cloned<br>
>>> Run pip install -r requirements.txt (Windows user make sure you are using<br>
>>> Python 2.7, not 3.x)<br>
>>> Build a section of the manual (for example make render)<br>
>>> Launch the contents_quicky.html inside of the html folder and browse the<br>
>>> freshly build render docs<br>
>>><br>
>>><br>
>>> That is a hundred times worse than trying to use the wiki manual. It is<br>
>>> mindboggingly offputting and not just incomprehensible but presents such a<br>
>>> hurdle that most people will stop at that point and forget being involved.<br>
>>><br>
>>> What it should say is.....<br>
>>><br>
>>> Read this (hopefully well written and elegantly presented) webpage which<br>
>>> explains how you register what you would like to do.<br>
>>><br>
>>> If worried about 'no nothings' writing drivel, that is why we invented<br>
>>> human editors. Also it is technically possible to have peer reviews of<br>
>>> submitted entries prior to making the entry official.<br>
>>><br>
>>> I was in the middle of working on my latest animation.....<br>
>>><br>
>>><br>
>>><br>
>><br>
>><br>
>> --<br>
>> +Rexford | Africa Center | WiR | WikiAfrica | User:Nkansahrexford<br>
>><br>
>><br>
>> _______________________________________________<br>
>> Bf-docboard mailing list<br>
>> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
>> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
>><br>
><br>
><br>
><br>
> _______________________________________________<br>
> Bf-docboard mailing list<br>
> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
><br>
><br>
><br>
> _______________________________________________<br>
> Bf-docboard mailing list<br>
> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
><br>
<br>
<br>
<br>
--<br>
- Campbell<br>
<br>
<br>
------------------------------<br>
<br>
Message: 4<br>
Date: Thu, 15 Jan 2015 00:19:20 +1100<br>
From: Campbell Barton <<a href="mailto:ideasman42@gmail.com">ideasman42@gmail.com</a>><br>
Subject: Re: [Bf-docboard] Being involved In documentation<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID:<br>
<<a href="mailto:CAEcf3Nzbhwi3hsJm8O1SiuMqBuHF_JS2FWkErkLPqREb-9FfLg@mail.gmail.com">CAEcf3Nzbhwi3hsJm8O1SiuMqBuHF_JS2FWkErkLPqREb-9FfLg@mail.gmail.com</a>><br>
Content-Type: text/plain; charset=UTF-8<br>
<br>
On Wed, Jan 14, 2015 at 11:54 PM, Abuelo S. B. Chdancer<br>
<<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>> wrote:<br>
> In reply to Pep Ribal....<br>
><br>
> Absolutely. The surprise is that some of what you suggest has been done, but<br>
> who would know? There are people who are listed as being in charge of bits<br>
> of the manual, the list is somewhere on some server, I have forgotten where.<br>
><br>
> It is an odd fact that more people want to code than explain the code. This<br>
> has been the case in the computer industry for decades and the lousy level<br>
> of most manuals is the result. My new hard disk drive comes with a manual<br>
> that warns not to connect the drive when the computer is on. How do you read<br>
> this manual? - It's in pdf format on the drive. (Anyone notice a problem<br>
> with this?)<br>
><br>
> I will circulate some guidelines for discussion....<br>
><br>
> On 14 January 2015 at 07:12, Pep Ribal <<a href="mailto:pepribal@gmail.com">pepribal@gmail.com</a>> wrote:<br>
>><br>
>> Hi all,<br>
>><br>
>> I understand the disappointment that the new documentation system has<br>
>> caused. I also think that it builds a big barrier for the people who want to<br>
>> help with documentation writing. It's true that the wiki made it much more<br>
>> simple to help, but I agree with Campbell that even the simplicity of the<br>
>> wiki didn't motivate people enough. And that means that technology was not<br>
>> the problem. I think the technology (wiki) was the right one to use, but the<br>
>> project lacked (and still lacks) something more.<br>
>><br>
>> The key question is: why isn't people motivated? For instance, Blender<br>
>> development has a huge entry barrier, compared to wiki, and even compared to<br>
>> the new reST-SVN system. However, activity is way bigger in development than<br>
>> in documentation. One does not expect that a project as big as Blender is<br>
>> suffering from a extremely low documentation development pace.<br>
>><br>
>> I've been working with Blender since many years ago, but I was away from<br>
>> it for a while. Now that I'm back, I see the same eternal problem that was<br>
>> present before: documentation is the worst of Blender, by far. And I don't<br>
>> see it changing any time soon, unless something is done. And I don't think a<br>
>> change in technology is the response (and even less a change that raises the<br>
>> entry barrier).<br>
>><br>
>> Motivation is the key. But how we manage to motivate people to contribute<br>
>> to the docs?<br>
>><br>
>> I think that some Project Management skills should be poured in. A<br>
>> "project manager" should be appointed. A few key positions should be filled<br>
>> (official writers), and an official documentation team should be set up. If<br>
>> we have a team of developers, an official team, with a clear coordinator and<br>
>> a clear team of key developers, each one responsible for his module, why not<br>
>> have the same for documenters? That's what the documentation project lacks.<br>
>> There is no official team. So there is not a feeling of "important<br>
>> department".<br>
>><br>
>> Why do we need an official team? Because there's no more motivating thing<br>
>> than feeling officially part of something. In this case, the ?official<br>
>> Blender documentation team?. And not only feeling that, but also seeing it,<br>
>> for instance, in the appropriate page in Blender website: names and<br>
>> functions of every ?official? member of that team. I think that would<br>
>> attract writers.<br>
>><br>
>> But it shouldn't only be a list of names in a web page. Being part of the<br>
>> team should offer additional ?privileges?. The more of them we can give, the<br>
>> more motivation writers will have.<br>
>><br>
>> What should be offered to writers besides credit? I think one of the most<br>
>> important things is attention from the developer responsible for the<br>
>> documented module. This is a crucial part in all this.<br>
>><br>
>> Perhaps other things could be offered, but as a start, these couple of<br>
>> things would help enough, I think.<br>
>><br>
>> Regards,<br>
>><br>
>> Pep.<br>
>><br>
>> El 14/01/15 a las 08:33, Abuelo S. B. Chdancer escribi?:<br>
>><br>
>> Hi to Nkansah Rexford,<br>
>><br>
>> A contributor should be able to go to a normal webpage.<br>
>><br>
>> Register what he would be interested in doing.<br>
>><br>
>> Be contacted by a real human who agrees the task.<br>
>><br>
>> The writer should be able to submit using email or a simple web based<br>
>> upload form. For the text.<br>
>><br>
>> If approved by an editor or by peer review the more complicated task of<br>
>> adding illustrations can be handle by some method.<br>
>><br>
>><br>
>><br>
>> On 14 January 2015 at 00:47, Nkansah Rexford <<a href="mailto:nkansahrexford@gmail.com">nkansahrexford@gmail.com</a>><br>
>> wrote:<br>
>>><br>
>>> Hello Chdancer,<br>
>>><br>
>>> I think you have a point, and its from a user who's got no idea what<br>
>>> those terms are.<br>
>>><br>
>>> However, look at it this way too. Trying to explain every single detail<br>
>>> of the steps will require another documentation on its own. "What repo is?",<br>
>>> "How to clone", "What is reST?", svn (what is even version control? duh!),<br>
>>> checkout (what am I buying?), pip, requirements.txt and so on.<br>
>>><br>
>>> Those are stuffs with detailed documentations on their own found<br>
>>> everywhere on the net. I don't think the getting started page on Blender<br>
>>> should aggregate all these information and present it to anyone who actually<br>
>>> wants to get started (beside's that'll be aggregating documentations into a<br>
>>> documentation).<br>
>>><br>
>>> Of course, more flesh can (and likely will) be added to those getting<br>
>>> started pages, but remember not everything can be covered or all the<br>
>>> terminologies can be expounded.<br>
>>><br>
>>> I think explaining every single thing on that page defeats the whole idea<br>
>>> of 'getting started'. Its not a training course. Its to get you started, so<br>
>>> they're pointers, offering guidance as to how to go about it.<br>
>>><br>
>>> Therefore, I think as someone who really wants to get started, doing a<br>
>>> bit more googling and reading outside the getting started page should make<br>
>>> things happen much easier, for both authors of get started pages and also<br>
>>> the 'get-startee' (bad english, but hope you get it)<br>
>>><br>
>>> I know its hard to understand pages like that, but I hope it gets<br>
>>> improved to the best possible to bridge the gap between devs and users.<br>
>>><br>
>>> rex<br>
>>><br>
>>> On Tuesday, January 13, 2015, Abuelo S. B. Chdancer<br>
>>> <<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>> wrote:<br>
>>>><br>
>>>> Campbell Barton reminded...<br>
>>>><br>
>>>> "While this is subjective, we have had contributions submitted via our<br>
>>>> project page:<br>
>>>><br>
>>>> <a href="https://developer.blender.org/tag/documentation/" target="_blank">https://developer.blender.org/tag/documentation/</a> "<br>
>>>><br>
>>>><br>
>>>> Guys, someone who USES Blender may not know the first thing about<br>
>>>> coding, someone who can write simple prose explaining to another person in<br>
>>>> clear language how to DO something artistic may be totally useless when it<br>
>>>> comes to installing software or plugging in a USB plug.<br>
>>>><br>
>>>> I bet a lot of possible contributors give up when they read this....<br>
>>>><br>
>>>> "We have migrated the content over to reST format, so that the manual<br>
>>>> can be built with Sphinx. A good amount of work is still required to<br>
>>>> complete the migration (learn more about the open tasks in Phabricator).<br>
>>>><br>
>>>> If you want to start contributing or want to have a look at the new<br>
>>>> manual, here we have some instructions.<br>
>>>><br>
>>>> How to build the docs locally<br>
>>>><br>
>>>> Checkout the Subversion repository svn checkout<br>
>>>> <a href="https://svn.blender.org/svnroot/bf-manual/trunk" target="_blank">https://svn.blender.org/svnroot/bf-manual/trunk</a><br>
>>>> Move to the location where the repo was cloned<br>
>>>> Run pip install -r requirements.txt (Windows user make sure you are<br>
>>>> using Python 2.7, not 3.x)<br>
>>>> Build a section of the manual (for example make render)<br>
>>>> Launch the contents_quicky.html inside of the html folder and browse the<br>
>>>> freshly build render docs<br>
>>>><br>
>>>><br>
>>>> That is a hundred times worse than trying to use the wiki manual. It is<br>
>>>> mindboggingly offputting and not just incomprehensible but presents such a<br>
>>>> hurdle that most people will stop at that point and forget being involved.<br>
>>>><br>
>>>> What it should say is.....<br>
>>>><br>
>>>> Read this (hopefully well written and elegantly presented) webpage which<br>
>>>> explains how you register what you would like to do.<br>
>>>><br>
>>>> If worried about 'no nothings' writing drivel, that is why we invented<br>
>>>> human editors. Also it is technically possible to have peer reviews of<br>
>>>> submitted entries prior to making the entry official.<br>
>>>><br>
>>>> I was in the middle of working on my latest animation.....<br>
>>>><br>
>>>><br>
>>>><br>
>>><br>
>>><br>
>>> --<br>
>>> +Rexford | Africa Center | WiR | WikiAfrica | User:Nkansahrexford<br>
>>><br>
>>><br>
>>> _______________________________________________<br>
>>> Bf-docboard mailing list<br>
>>> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
>>> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
>>><br>
>><br>
>><br>
>><br>
>> _______________________________________________<br>
>> Bf-docboard mailing list<br>
>> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
>> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
>><br>
>><br>
>><br>
>> _______________________________________________<br>
>> Bf-docboard mailing list<br>
>> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
>> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
>><br>
><br>
><br>
> _______________________________________________<br>
> Bf-docboard mailing list<br>
> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
><br>
<br>
<br>
<br>
--<br>
- Campbell<br>
<br>
<br>
------------------------------<br>
<br>
Message: 5<br>
Date: Wed, 14 Jan 2015 14:30:27 +0100<br>
From: "Abuelo S. B. Chdancer" <<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>><br>
Subject: [Bf-docboard] What has been done so far....<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID:<br>
<<a href="mailto:CAFH9JFNMK8B2sNV4zV3MdxNnfc028Jnfg7YGz_zCjswzqqYf%2Bg@mail.gmail.com">CAFH9JFNMK8B2sNV4zV3MdxNnfc028Jnfg7YGz_zCjswzqqYf+g@mail.gmail.com</a>><br>
Content-Type: text/plain; charset="utf-8"<br>
<br>
The technical approach has been to make better the bits that can be made<br>
better by technology. I saw that the new website has a search box and side<br>
panel navigation. I vaguely registered that there's some kind of software<br>
available for editors to get into the website and jiggle around with the<br>
content in some way. Beyond that I haven't a clue what the tech people are<br>
talking about.<br>
<br>
I think they have probably done an excellent job.<br>
<br>
They have done what is in their power to do, and it seems that they have<br>
copied over lots of the old content as a default because no one has decided<br>
the basics of<br>
<br>
what type of manual we want...<br>
<br>
what it should contain and essentially<br>
<br>
its very purpose.<br>
Somewhere far away on a web server there is a list of poeple who may have<br>
made these decisions, but I am unaware of any of that.<br>
<br>
I will circulate a draft soon...<br>
-------------- next part --------------<br>
An HTML attachment was scrubbed...<br>
URL: <a href="http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/8fb3e615/attachment-0001.htm" target="_blank">http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/8fb3e615/attachment-0001.htm</a><br>
<br>
------------------------------<br>
<br>
Message: 6<br>
Date: Thu, 15 Jan 2015 00:39:49 +1100<br>
From: Campbell Barton <<a href="mailto:ideasman42@gmail.com">ideasman42@gmail.com</a>><br>
Subject: Re: [Bf-docboard] What has been done so far....<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID:<br>
<CAEcf3Nzz7VQssKKPzGCx5GhOqN=<a href="mailto:oB3DmJtj808CgFN4UTzyxWA@mail.gmail.com">oB3DmJtj808CgFN4UTzyxWA@mail.gmail.com</a>><br>
Content-Type: text/plain; charset=UTF-8<br>
<br>
On Thu, Jan 15, 2015 at 12:30 AM, Abuelo S. B. Chdancer<br>
<<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>> wrote:<br>
> The technical approach has been to make better the bits that can be made<br>
> better by technology. I saw that the new website has a search box and side<br>
> panel navigation. I vaguely registered that there's some kind of software<br>
> available for editors to get into the website and jiggle around with the<br>
> content in some way. Beyond that I haven't a clue what the tech people are<br>
> talking about.<br>
><br>
> I think they have probably done an excellent job.<br>
><br>
> They have done what is in their power to do, and it seems that they have<br>
> copied over lots of the old content as a default because no one has decided<br>
> the basics of<br>
><br>
> what type of manual we want...<br>
><br>
> what it should contain and essentially<br>
><br>
> its very purpose.<br>
><br>
> Somewhere far away on a web server there is a list of poeple who may have<br>
> made these decisions, but I am unaware of any of that.<br>
><br>
> I will circulate a draft soon...<br>
<br>
Yep, this is a conversation we need to have (sooner then later).<br>
<br>
It seems people who are involved in the writing side of making a<br>
manual are just not very active/vocal.<br>
<br>
I mailed the list asking for feedback on writing styles (as in style<br>
for the actual content) and got no response.<br>
<br>
It would be really good if people on this list who are interested to<br>
be involved as writers would speak up more and try to help get a<br>
clearer focus for the manual.<br>
<br>
<br>
------------------------------<br>
<br>
Message: 7<br>
Date: Wed, 14 Jan 2015 14:47:21 +0100<br>
From: "Abuelo S. B. Chdancer" <<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>><br>
Subject: Re: [Bf-docboard] What has been done so far....<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID:<br>
<CAFH9JFNncHRdpiA665-MxHWP1EcbJp=tJhRJVH18MtJWS=<a href="mailto:X68Q@mail.gmail.com">X68Q@mail.gmail.com</a>><br>
Content-Type: text/plain; charset="utf-8"<br>
<br>
Excellent.<br>
<br>
I strongly suspect that they are stunned into silence by mutual<br>
incomprehension and the widespread feeling that what non-technical people<br>
think of as the essential basics are what technical people think of as<br>
'extras we can add on later', but maybe they are just snoozing after a hard<br>
day sharpening pencils , who knows. Wait a few minutes and I will put<br>
forward my first suggestions<br>
<br>
<br>
<br>
<br>
On 14 January 2015 at 14:39, Campbell Barton <<a href="mailto:ideasman42@gmail.com">ideasman42@gmail.com</a>> wrote:<br>
<br>
> On Thu, Jan 15, 2015 at 12:30 AM, Abuelo S. B. Chdancer<br>
> <<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>> wrote:<br>
> > The technical approach has been to make better the bits that can be made<br>
> > better by technology. I saw that the new website has a search box and<br>
> side<br>
> > panel navigation. I vaguely registered that there's some kind of software<br>
> > available for editors to get into the website and jiggle around with the<br>
> > content in some way. Beyond that I haven't a clue what the tech people<br>
> are<br>
> > talking about.<br>
> ><br>
> > I think they have probably done an excellent job.<br>
> ><br>
> > They have done what is in their power to do, and it seems that they have<br>
> > copied over lots of the old content as a default because no one has<br>
> decided<br>
> > the basics of<br>
> ><br>
> > what type of manual we want...<br>
> ><br>
> > what it should contain and essentially<br>
> ><br>
> > its very purpose.<br>
> ><br>
> > Somewhere far away on a web server there is a list of poeple who may have<br>
> > made these decisions, but I am unaware of any of that.<br>
> ><br>
> > I will circulate a draft soon...<br>
><br>
> Yep, this is a conversation we need to have (sooner then later).<br>
><br>
> It seems people who are involved in the writing side of making a<br>
> manual are just not very active/vocal.<br>
><br>
> I mailed the list asking for feedback on writing styles (as in style<br>
> for the actual content) and got no response.<br>
><br>
> It would be really good if people on this list who are interested to<br>
> be involved as writers would speak up more and try to help get a<br>
> clearer focus for the manual.<br>
> _______________________________________________<br>
> Bf-docboard mailing list<br>
> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
><br>
-------------- next part --------------<br>
An HTML attachment was scrubbed...<br>
URL: <a href="http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/59c9cd59/attachment-0001.htm" target="_blank">http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/59c9cd59/attachment-0001.htm</a><br>
<br>
------------------------------<br>
<br>
Message: 8<br>
Date: Wed, 14 Jan 2015 15:12:42 +0100<br>
From: "Abuelo S. B. Chdancer" <<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>><br>
Subject: [Bf-docboard] Specific plans and discussion of what our<br>
manual should be and how to get it<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID:<br>
<<a href="mailto:CAFH9JFMKjYPT5OyaYgBtMMybjMs0NZTmKvzshbYgQij4W2ys5A@mail.gmail.com">CAFH9JFMKjYPT5OyaYgBtMMybjMs0NZTmKvzshbYgQij4W2ys5A@mail.gmail.com</a>><br>
Content-Type: text/plain; charset="utf-8"<br>
<br>
Top level design:<br>
<br>
What should a manual be and how do we get one?<br>
<br>
1) Quick reference guide to all commands?<br>
<br>
2) Topic based manual of what you might want to do and how to do it?<br>
<br>
3) A place to learn step by step?<br>
<br>
Lower level design:<br>
<br>
What is a normal page to look like?<br>
<br>
How should one page lead or connect to another? (Has the tech already set<br>
this?)<br>
<br>
What should the overall plan for the entire work be?<br>
<br>
Contributors:<br>
<br>
Finding that rare combination of someone who intimately knows parts of<br>
Blender and is willing and able to explain it to someone who doesn't<br>
understand shouldn't be messed up by also requiring that person to be<br>
technically proficient and willing to learn new software simply to tell<br>
their story.<br>
<br>
If that software is needed to get the text and pictures into the server -<br>
let those who use it be *sub-editors* and let the *authors* communicate<br>
with sub-editors using simple software that everyone already has - email &<br>
browser.<br>
<br>
I would tell other potential contributors that they need to indicate in a<br>
simple webform what they feel able to help on, and tell them that sending<br>
in their contribution will be technically similar to posting a comment on a<br>
website - nothing to download, no programming skills needed.<br>
<br>
The various ideas would need to be cut down to practical designs and could<br>
then be again displayed on webpages for public review.<br>
<br>
When the design of the work has been decided which includes details of what<br>
individual pages should have in common and what should be different the<br>
minor stylistic decisions can be made about whether writing is to say "You<br>
can" rather than "It is possible to.."<br>
<br>
We need a few web pages that everyone who downloads blender would be asked<br>
to review asking them to rate which concepts they think would be useful for<br>
them in learning or using Blender.<br>
<br>
I would do a survey of users to try to understand what they/we need or want<br>
from documentation.<br>
<br>
I would send an email to anyone who downs Blender, about 2 weeks later<br>
asking them to comment on what causes them problems, on where they look for<br>
information, on how they are learning. I would read them all to get a feel<br>
for the problem.<br>
<br>
So I suggest the following:<br>
<br>
Those who already have downloaded whatever that stuff is that I couldn't<br>
even be bothered to read - they should be initially *sub-editors *who can<br>
receive contributions from other simpler folks like me, that *sub-editor*<br>
then uses that software stuff to get the data onto the server.<br>
<br>
Some web page creating type is needed to set-up the following fairly simple<br>
webpages that I am suggesting, or something similar where normal<br>
contributors can register their willingness and their self-claimed level of<br>
expertise. I would be happy to work with the webpage creator.<br>
<br>
I would be happy to help plan a few web pages that everyone who downloads<br>
blender would be asked to review asking them to rate which concepts they<br>
think would be useful for them in learning or using Blender.<br>
<br>
The server should send an email anyone who downs Blender, about 2 weeks<br>
later asking them to comment on what causes them problems, on where they<br>
look for information, on how they are learning. We should all read them all<br>
to get a feel for the problem.<br>
<br>
It may be that others on this list that is out there somewhere have much<br>
better ideas than mine, but if we don't come up with a better plan this is<br>
the default that I suggest:<br>
<br>
I and a web page creator put on Blender.org the following new webpages<br>
directly linked as the documentation page.<br>
<br>
"Register in this form if you would like to be involved in creating a great<br>
manual for a great program."<br>
<br>
The form would contain questions for the contributor to define in what way<br>
they can help.<br>
<br>
They can choose to be<br>
<br>
*sub-editors* who download software and get their fingers into the servers<br>
data or<br>
<br>
*authors * who write explaining command or who write explaining methods or<br>
<br>
*contributors* who want to voice what they would like to see in the manual<br>
but who are not capable of actually doing it (newbies have the right to say<br>
what they need, but obviously they can't provide it)<br>
<br>
Decisions or plans of what the manual should contain and BE, would be<br>
published on those pages with feedback forms to check if it's what users<br>
probably want.<br>
<br>
Please make your suggestions.<br>
<br>
Do you want to build those webpages?<br>
-------------- next part --------------<br>
An HTML attachment was scrubbed...<br>
URL: <a href="http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/901d3a62/attachment-0001.htm" target="_blank">http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/901d3a62/attachment-0001.htm</a><br>
<br>
------------------------------<br>
<br>
Message: 9<br>
Date: Wed, 14 Jan 2015 16:08:41 +0100<br>
From: brita <<a href="mailto:britalmeida@gmail.com">britalmeida@gmail.com</a>><br>
Subject: Re: [Bf-docboard] Specific plans and discussion of what our<br>
manual should be and how to get it<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID:<br>
<<a href="mailto:CAHaG9ayBR-Wn4-LRTEMWHGi5goWFVTDQ-TujPn-Co_6qr0dmQw@mail.gmail.com">CAHaG9ayBR-Wn4-LRTEMWHGi5goWFVTDQ-TujPn-Co_6qr0dmQw@mail.gmail.com</a>><br>
Content-Type: text/plain; charset="utf-8"<br>
<br>
These are mostly all topics that have been discussed on the wiki channel,<br>
considering the experience of several people.<br>
<br>
The manual is the manual. It is not a tutorial, it is not the python<br>
reference, it should not teach you graphics concepts as what is a camera or<br>
how to animate.<br>
There are other and more appropriate places for that.<br>
<br>
The manual is a comprehensive set of pages that cover the usability of<br>
Blender.<br>
<br>
Blender is also a very big software that encompasses many areas. It is<br>
difficult to make a linear manual that goes through everything only once in<br>
the right order, and that is short and readable while containing all the<br>
information that a user of varying expertise and background may ever wish<br>
for.<br>
<br>
The new tentative structure of the manual has been reviewed in the last two<br>
weeks. It now mainly needs a lot of reviewing and filling, making also sure<br>
that more people get on board and that the technology supports a good<br>
workflow.<br>
<br>
As to the organization of the collaborators, it is described in<br>
<a href="http://www.blender.org/manual/about/introduction.html" target="_blank">http://www.blender.org/manual/about/introduction.html</a><br>
that before was in <a href="http://blender.org/documentation" target="_blank">blender.org/documentation</a>.<br>
The information about the documentation is being unified in an hopefully<br>
clearer.<br>
<br>
The main idea is, there are section owners that get to decide things about<br>
their own sections and regular contributors. A new contributor should<br>
submit their changes for review before gaining access, as also explained in<br>
that documentation.<br>
The table with who owns what is being worked on right now. With the current<br>
status of the documentation, there are a lot of abandoned areas that need<br>
to be picked up.<br>
<br>
<br>
It is against Blender's philosophy to spam everyone that uses Blender with<br>
emails or polls or to silently fish information.<br>
People should be involved in their own way, at their own pace if they have<br>
such interest.<br>
<br>
It is important to communicate well (where do you find tutorials, what do<br>
you do if you are starting a commercial project .. ). The ways in which<br>
blender communicates, (mainly in <a href="http://blender.org" target="_blank">blender.org</a>) are always a work in progress.<br>
People are different and have their own ways and sense of privacy. Projects<br>
such as <a href="http://blender.org" target="_blank">blender.org</a> or the cloud or blender stackexchange or the manual<br>
need to grow on themselves. People will find them by needing and searching.<br>
<br>
<br>
Then this:<br>
"<br>
Those who already have downloaded whatever that stuff is that I couldn't<br>
even be bothered to read<br>
"<br>
is not really nice. If you really want to help, I suggest you actually read<br>
the<br>
<a href="http://www.blender.org/manual/about" target="_blank">http://www.blender.org/manual/about</a><br>
following the instructions to get started contributing.<br>
You could, for instance, review the User Preferences section to make sure<br>
that all options are up to date. Or get started with one of the new Editor<br>
pages.<br>
<br>
<br>
In?s Almeida / brita_<br>
-------------- next part --------------<br>
An HTML attachment was scrubbed...<br>
URL: <a href="http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/70e2ab27/attachment-0001.htm" target="_blank">http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/70e2ab27/attachment-0001.htm</a><br>
<br>
------------------------------<br>
<br>
Message: 10<br>
Date: Wed, 14 Jan 2015 17:22:03 +0200<br>
From: Greg Zaal <<a href="mailto:gregzzmail@gmail.com">gregzzmail@gmail.com</a>><br>
Subject: Re: [Bf-docboard] Specific plans and discussion of what our<br>
manual should be and how to get it<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID:<br>
<CAN5-zsMvuOC6PZJtotEanh6jj7rub2sETc41C_RYCcvH=<a href="mailto:vZ2yA@mail.gmail.com">vZ2yA@mail.gmail.com</a>><br>
Content-Type: text/plain; charset="iso-8859-1"<br>
<br>
Hey Abuelo,<br>
<br>
We discussed what the new manual should be a little while ago on this list<br>
- there seemed to be a general consensus that it should be both a technical<br>
reference ("button X does this") and a topic-driven guide. Different<br>
sections of the manual are suited to either one or both of those. (See the<br>
archives<br>
<<a href="http://lists.blender.org/pipermail/bf-docboard/2015-January/thread.html" target="_blank">http://lists.blender.org/pipermail/bf-docboard/2015-January/thread.html</a>>,<br>
in thread "Proposal for restructuring the user manual").<br>
<br>
Breaking it up into sub-editors, authors and contributors is an interesting<br>
idea. I agree that someone should be able to suggest a change to the manual<br>
without needing to set up SVN, but this can already be done by creating a<br>
task here: <a href="https://developer.blender.org/maniphest/task/create/?project=53" target="_blank">https://developer.blender.org/maniphest/task/create/?project=53</a>.<br>
Being a sub-editor would be a pretty crappy "job" I think - receive emails<br>
from random people demanding you to make some change, and then you're left<br>
to sort out correct formatting, uploading images and commit it.<br>
<br>
Sending an email to every blender user 2 weeks after they download it is<br>
not acceptable at all IMO, but you can easily start a thread on<br>
<a href="http://blenderartists.org" target="_blank">blenderartists.org</a> to ask them (possibly do a poll there).<br>
<br>
I think it would be best if you could join our IRC channel for a few<br>
minutes (click here<br>
<<a href="http://webchat.freenode.net?nick=abuelo...&channels=%23blenderwiki&uio=d4" target="_blank">http://webchat.freenode.net?nick=abuelo...&channels=%23blenderwiki&uio=d4</a>>,<br>
type in the captcha, and you're in) to chat with us - just to make sure<br>
we're all on the same page and to avoid starting discussions that have<br>
already been had.<br>
<br>
Finally, I'd really appreciate if you try to set up SVN and make some edits<br>
to the manual (here's a simple guide I wrote to help:<br>
<a href="http://blender.org/manual/about/install/windows.html" target="_blank">http://blender.org/manual/about/install/windows.html</a>) - it's really not as<br>
hard or complicated as you think it is - I'm primarily an artist myself.<br>
<br>
Cheers,<br>
Greg Zaal<br>
<br>
On 14 January 2015 at 16:12, Abuelo S. B. Chdancer <<a href="mailto:playadance@gmail.com">playadance@gmail.com</a>><br>
wrote:<br>
<br>
> Top level design:<br>
><br>
> What should a manual be and how do we get one?<br>
><br>
> 1) Quick reference guide to all commands?<br>
><br>
> 2) Topic based manual of what you might want to do and how to do it?<br>
><br>
> 3) A place to learn step by step?<br>
><br>
> Lower level design:<br>
><br>
> What is a normal page to look like?<br>
><br>
> How should one page lead or connect to another? (Has the tech already set<br>
> this?)<br>
><br>
> What should the overall plan for the entire work be?<br>
><br>
> Contributors:<br>
><br>
> Finding that rare combination of someone who intimately knows parts of<br>
> Blender and is willing and able to explain it to someone who doesn't<br>
> understand shouldn't be messed up by also requiring that person to be<br>
> technically proficient and willing to learn new software simply to tell<br>
> their story.<br>
><br>
> If that software is needed to get the text and pictures into the server -<br>
> let those who use it be *sub-editors* and let the *authors* communicate<br>
> with sub-editors using simple software that everyone already has - email &<br>
> browser.<br>
><br>
> I would tell other potential contributors that they need to indicate in a<br>
> simple webform what they feel able to help on, and tell them that sending<br>
> in their contribution will be technically similar to posting a comment on a<br>
> website - nothing to download, no programming skills needed.<br>
><br>
> The various ideas would need to be cut down to practical designs and could<br>
> then be again displayed on webpages for public review.<br>
><br>
> When the design of the work has been decided which includes details of<br>
> what individual pages should have in common and what should be different<br>
> the minor stylistic decisions can be made about whether writing is to say<br>
> "You can" rather than "It is possible to.."<br>
><br>
> We need a few web pages that everyone who downloads blender would be<br>
> asked to review asking them to rate which concepts they think would be<br>
> useful for them in learning or using Blender.<br>
><br>
> I would do a survey of users to try to understand what they/we need or<br>
> want from documentation.<br>
><br>
> I would send an email to anyone who downs Blender, about 2 weeks later<br>
> asking them to comment on what causes them problems, on where they look for<br>
> information, on how they are learning. I would read them all to get a feel<br>
> for the problem.<br>
><br>
> So I suggest the following:<br>
><br>
> Those who already have downloaded whatever that stuff is that I couldn't<br>
> even be bothered to read - they should be initially *sub-editors *who can<br>
> receive contributions from other simpler folks like me, that *sub-editor*<br>
> then uses that software stuff to get the data onto the server.<br>
><br>
> Some web page creating type is needed to set-up the following fairly<br>
> simple webpages that I am suggesting, or something similar where normal<br>
> contributors can register their willingness and their self-claimed level of<br>
> expertise. I would be happy to work with the webpage creator.<br>
><br>
> I would be happy to help plan a few web pages that everyone who downloads<br>
> blender would be asked to review asking them to rate which concepts they<br>
> think would be useful for them in learning or using Blender.<br>
><br>
> The server should send an email anyone who downs Blender, about 2 weeks<br>
> later asking them to comment on what causes them problems, on where they<br>
> look for information, on how they are learning. We should all read them all<br>
> to get a feel for the problem.<br>
><br>
> It may be that others on this list that is out there somewhere have much<br>
> better ideas than mine, but if we don't come up with a better plan this is<br>
> the default that I suggest:<br>
><br>
> I and a web page creator put on Blender.org the following new webpages<br>
> directly linked as the documentation page.<br>
><br>
> "Register in this form if you would like to be involved in creating a<br>
> great manual for a great program."<br>
><br>
> The form would contain questions for the contributor to define in what way<br>
> they can help.<br>
><br>
> They can choose to be<br>
><br>
> *sub-editors* who download software and get their fingers into the<br>
> servers data or<br>
><br>
> *authors * who write explaining command or who write explaining methods<br>
> or<br>
><br>
> *contributors* who want to voice what they would like to see in the<br>
> manual but who are not capable of actually doing it (newbies have the right<br>
> to say what they need, but obviously they can't provide it)<br>
><br>
> Decisions or plans of what the manual should contain and BE, would be<br>
> published on those pages with feedback forms to check if it's what users<br>
> probably want.<br>
><br>
> Please make your suggestions.<br>
><br>
> Do you want to build those webpages?<br>
><br>
><br>
> _______________________________________________<br>
> Bf-docboard mailing list<br>
> <a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
> <a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
><br>
><br>
-------------- next part --------------<br>
An HTML attachment was scrubbed...<br>
URL: <a href="http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/987cce19/attachment-0001.htm" target="_blank">http://lists.blender.org/pipermail/bf-docboard/attachments/20150114/987cce19/attachment-0001.htm</a><br>
<br>
------------------------------<br>
<br>
Message: 11<br>
Date: Thu, 15 Jan 2015 08:35:48 +0800<br>
From: Pep Ribal <<a href="mailto:pepribal@gmail.com">pepribal@gmail.com</a>><br>
Subject: Re: [Bf-docboard] Being involved In documentation<br>
To: Blender Documentation Project <<a href="mailto:bf-docboard@blender.org">bf-docboard@blender.org</a>><br>
Message-ID:<br>
<CAOOWns6eKjrCHgWK5xEA4m+52=<a href="mailto:kby-wLfP%2B70ptGq5Xb2sFKig@mail.gmail.com">kby-wLfP+70ptGq5Xb2sFKig@mail.gmail.com</a>><br>
Content-Type: text/plain; charset=UTF-8<br>
<br>
2015-01-14 21:19 GMT+08:00, Campbell Barton <<a href="mailto:ideasman42@gmail.com">ideasman42@gmail.com</a>>:<br>
> On Wed, Jan 14, 2015 at 5:12 PM, Pep Ribal <<a href="mailto:pepribal@gmail.com">pepribal@gmail.com</a>> wrote:<br>
>> I think that some Project Management skills should be poured in. A<br>
>> "project<br>
>> manager" should be appointed. A few key positions should be filled<br>
>> (official<br>
>> writers), and an official documentation team should be set up. If we have<br>
>> a<br>
>> team of developers, an official team, with a clear coordinator and a clear<br>
>> team of key developers, each one responsible for his module, why not have<br>
>> the same for documenters? That's what the documentation project lacks.<br>
>> There<br>
>> is no official team. So there is not a feeling of "important department".<br>
><br>
> Agree, but we need someone who is naturally good in the role of<br>
> helping people work together, not just someone who comes in and says<br>
> they will tell others what to do.<br>
><br>
<br>
If we agree that this position is needed, my suggestion is to look for<br>
that person right away. In any company, it's the obvious thing to do<br>
(needed? hired!), so why not make an announcement right away, using<br>
the lists, blender website, etc.? Something like:<br>
<br>
"Team leader wanted, responsible for the development of the official<br>
Blender documentation. Skills needed: proven leadership, project<br>
management, Blender knowledge, etc. (just an example)"<br>
<br>
I think it can turn the Blender manual status from "stuck" to "in progress".<br>
<br>
If that person were found, and he/she were good enough, he/she would<br>
be able to motivate people and build up an appropriate team of<br>
writers, for sure.<br>
<br>
Pep.<br>
<br>
<br>
------------------------------<br>
<br>
_______________________________________________<br>
Bf-docboard mailing list<br>
<a href="mailto:Bf-docboard@blender.org">Bf-docboard@blender.org</a><br>
<a href="http://lists.blender.org/mailman/listinfo/bf-docboard" target="_blank">http://lists.blender.org/mailman/listinfo/bf-docboard</a><br>
<br>
<br>
End of Bf-docboard Digest, Vol 119, Issue 11<br>
********************************************<br>
</blockquote></div><br></div>