<div dir="ltr"><div><div><div>Hey guys,<br></div><div><br>Overall, I like the proposal and agree with most of the comments so far, with a few little notes:<br><br></div>About videos: I agree that they're generally a problem to maintain and internationalize, though a video with no voice which simply shows the results of something (e.g. ocean modifier includes: <a href="http://vimeo.com/18911131" target="_blank">http://vimeo.com/18911131</a> ) is perfectly fine imo.<br><br></div>A section on editors is a good idea, as long as we're not duplicating anything too much. I see it as a place to describe the editors themselves, and link to the other relevant sections when mentioning a feature.<br><br></div><div>Now about restructuring the whole manual:<br><br>When will "good timing" come?
I'd prefer if we get all big restructuring done fairly soon (before February perhaps). It doesn't have to be a gargantuan task undertaken by only a handful of people - it may be easier to start from the ground up and get module owners and volunteers to work on a section each.<br><br>These people would become the "section owners" mentioned in <a href="http://blender.org/documentation/contribute">http://blender.org/documentation/contribute</a>. We could rename the /manual folder to /manual_old, and then they could scrub through the old manual for their relevant content and move them to a new /manual folder. This way, it'll be easy to tell what's still left to move (stuff still in /manual_old), and keep note of where things were moved to so that it'll be easier to fix all the broken links caused by the move.</div><div><br></div><div>Cheers,<br></div><div>Greg<br></div></div><div class="gmail_extra"><br><div class="gmail_quote">On 28 December 2014 at 01:36, Campbell Barton <span dir="ltr"><<a href="mailto:ideasman42@gmail.com" target="_blank">ideasman42@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">Thanks for the feedback.<br>
<br>
Some of these more detailed points seem reasonable but I dont have a<br>
strong opinion on them - so skipping those. Commented on others<br>
though.<br>
<span class=""><br>
On Sun, Dec 28, 2014 at 10:04 AM, brita <<a href="mailto:britalmeida@gmail.com">britalmeida@gmail.com</a>> wrote:<br>
> replying with feedback on the proposal and on some things that I currently<br>
> think could be improved.<br>
><br>
> tl;dr:<br>
> - I would start by focusing on more introductory sections and hold on other<br>
> big restructurings for whenever is a good timing. Doing the 'Editors' would<br>
> be big.<br>
<br>
</span>Agree restructing a single section can be a good start, at some point<br>
we might want to restructure all (Having a plan for final structure is<br>
good, even if we don't do all at once).<br>
<span class=""><br>
> - We need to speed up on having a platform for better communication and task<br>
> management<br>
<br>
</span>Isnt this phabricator?<br>
<span class=""><br>
> - I would not do an 'Advanced' section.<br>
<br>
</span>No strong opinion.<br>
<span class=""><br>
> - I would not put any videos<br>
<br>
</span>Agree, I rather not do videos, too much risk we make it once and it<br>
never gets updated.<br>
<br>
Later on if we have good docs, some short intro video the author can<br>
re-record (when Blender changes), may be OK. but right now it feels<br>
like taking on more work then we have time for.<br>
<span class=""><br>
> I would maintain a 'Getting Started' as is now, and not replace it with the<br>
> current 'Basics' section (or did you @gaia mean only change the title?) ,<br>
> 'Introduction' - keep<br>
> 'Installation' - keep, but do a really big cleanup, put the<br>
> 'Troubleshooting' here too, also trimmed<br>
><br>
> Then the mess starts, I don't really like videos as they are harder to keep<br>
> up to date, and to internationalize. I don't oppose either, if we define a<br>
> good infrastructure to support videos, and<br>
> if they are not many.<br>
> I think that they should not replace text, so with or without video:<br>
<br>
</span>Agree, as I said above, some very short video link might be OK, but<br>
further, I wouldn't want to rely on video as a content source for the<br>
manual.<br>
<div><div class="h5"><br>
> 'Preferences' - right after installation. this can have both a 'setting up<br>
> blender for the first time', with 'do you have numpad? 3button mouse?..'<br>
> simple stuff, and a full reference even though users won't understand some<br>
> of the 3d space manipulation nuances. otherwise, this can go after basics.<br>
> The internationalization of the UI sould be mentioned as soon as possible<br>
> for users who are following translated manuals.<br>
><br>
> 'Interface' explaining windows/editors, splitting, etc and how to get<br>
> around, then<br>
><br>
> 'Basics' - with:<br>
> - setting the default scene,<br>
> - mentioning preferences (if not mentioned before)<br>
> - help system<br>
> - quick rendering. also say we have different render engines<br>
> - quick whatever so that people can just get around before delving deeper<br>
> on anything<br>
> - take screenshot and screencast away from this section<br>
><br>
> '3D Interaction' - this section currently looks quite complicated and not<br>
> very well encapsulated.<br>
><br>
> 'Data System' - I would put this very early, not in advanced, so that people<br>
> understand quickly what are objects, and datablocks, users, fake users and<br>
> that data with no users gets deleted, how linking and appending works. The<br>
> philosophy of scenes and worlds, and the outliner. I really think this is<br>
> part of the basics, not advanced.<br>
><br>
><br>
> All the other sections and generic structure:<br>
><br>
> As for the Editors organization, I have mixed feelings about it. it is ever<br>
> a complex subject.<br>
> I do agree with having a reference per editor.<br>
> About the structure, some editor pages fit nicely inside other sections (eg.<br>
> outliner in data system, python console in scripting, 3d view in 3d<br>
> interaction..). Some are generic or fit in multiple sections, like<br>
> 'properties'<br>
> So, have a list of editors, or the editors inside more or less subjectively<br>
> appropriate sections?<br>
> I would propose, mentioning the editors inside wherever it makes sense, with<br>
> workflow guided explanations, and have a section 'Editors' with all of them<br>
> to be used as reference.<br>
> This is quite a big restructure, though, and dangerous to have information<br>
> repeated, I would hold off on it for now.<br>
><br>
> The whole manual probably needs a review to support better the fact that<br>
> there are multiple render engines. I see that 'blender internal' 'cycles'<br>
> and 'freestyle' are not easy to spot in the current structure.<br>
> These were lvl1 chapters in the wiki, why was this changed?<br>
><br>
> 'World' - the stars feature doesn't exist anymore.. so.. trim and include<br>
> this in rendering?<br>
> Modeling, Modifiers, Rigging, Constraints, Animation, Materials, Textures,<br>
> Rendering, Compositing<br>
><br>
> 'Glossary' are we using that? do we intend to?<br>
<br>
</div></div>This is new, a feature of sphinx/rst. It means we can reference<br>
anything from the glossary. eg:<br>
<br>
Text about :term:`Manifold Mesh` etc.<br>
<br>
I think its good to keep, we've already de-duplicated a bit of content<br>
by using it.<br>
<span class=""><br>
> I would avoid calling 'advanced' to anything. It really depends on the<br>
> background of the user. for some rigging is advanced, for others it's<br>
> exactly what they want to read and having it on an 'advanced' section, makes<br>
> it look like that's not a normal use case for Blender. same for 'physics' or<br>
> 'motion tracking' or anything really.<br>
> Putting 'Extending Blender' in advanced, will scare users from scripting.<br>
> 'Data Systems', imho should be after 'basics', and 'Game Engine' is also not<br>
> advanced (more like unsupported, but it shouldn't be more advanced than MT<br>
> or video editing).<br>
<br>
</span>Agree, if we do have an advanced section, it should be for _really_<br>
advanced stuff, though if its kept small and documents exceptional<br>
use-cases or internal details... it could be OK.<br>
<br>
We could just not add for now, and only add if it makes sense, later<br>
on (setting up cluster of physics sim baking PC's maybe *advanced*,<br>
but also outside the scope of the manual).<br>
<span class="im HOEnZb"><br>
><br>
> @gaia if going forward with the Editors, would you be available to do it?<br>
> If you are motivated to do it now, I say 'don't hold off and go for it!'<br>
> Even if you don't have the knowledge for all the editors, it would be good<br>
> to have something more. But not being easy to deal with structuring, data<br>
> duplication and massive reviewing of sections, I just meant that it is a lot<br>
> of trouble when there are a lot of other high priority things that are<br>
> easier to tackle first.<br>
><br>
> cheers!<br>
> Inês Almeida / brita_<br>
><br>
><br>
</span><span class="im HOEnZb">> _______________________________________________<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>
</span><span class="HOEnZb"><font color="#888888">--<br>
- Campbell<br>
</font></span><div class="HOEnZb"><div class="h5">_______________________________________________<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>
</div></div></blockquote></div><br></div>