Blender User Manual - Official Call for Help!

Hey everyone :slight_smile:

It’s no secret that the manual is a big mess and contains lots of outdated information and screenshots left over from the 2.4 era. Some sections do nothing more than tell you the same basic info you found in the tooltip, or simply don’t have any information about the tool at all because nobody ever bothered to write anything.

All of those problems inherently come from a user manual that is written by many people, some less experienced than others. Developers often have to document their features themselves, but we all know that they have much more important things to do.

But this is where you come in!

We’re looking for anyone who’d like to help us out in whatever capacity they like, be it fixing a single spelling mistake, or documenting every missing compositing node :slight_smile:

There’s a fair amount of work to do, but at the moment our biggest issues with the manual are:

  • Old information and screenshots (eg)
  • Too much text! Some pages tell you far more than you need to know, or go completely off-topic (eg)
  • Unfinished/blank pages (eg, eg)
  • Pages in completely the wrong place (eg: ruler & protractor in the grease pencil chapter)

If you’d like to get involved, we could really use your help :slight_smile: Check out http://blender.org/manual/about/contribute.html

Our goal is to have at least one person responsible for each chapter of the manual, letting them do whatever they see fit to make it better and keep it up to date (be it just fixing things, or rewriting it entirely)


In case you’re unaware, the Blender User Manual has moved from the old Wiki system to a new one at blender.org/manual. This doesn’t change much from a reader’s point of view, but it’s definitely much nicer for those writing the manual.

Here’s a page explaining the reasons why we moved away from the wiki, including pros and cons of each system.

I know at first glance it seems like a ridiculously convoluted technical challenge to set up, but it’s something you only have to do once and should take less than half an hour. Once you’re ready, it’s a simple matter of editing text files.

If you are not used to SVN and are struggling with the technology, head on over to #blenderwiki on IRC and we’ll help you get started quickly :slight_smile:

Finally, a couple links you might find handy:


To answer some questions you might have before you ask them:

Q: Why did you switch and not just improve the wiki?
A: We decided that the wiki wasn’t really working, and although there is a slightly higher barrier of entry in this new system, the pros outweigh the cons. More details are explained here: http://blender.org/manual/about/migration.html

Q: This whole SVN/python/sphinx thing is really confusing, is there any way I can contribute to the manual without it?
A: There is! If you find a problem on a certain page or would like to suggest an improvement, just make a Task for us and someone will fix it for you. If you’re planning on doing this a lot, it’d be best for everyone if you take a few minutes to set up the software for your self to save us some time.

Q: I’d like to help, what can I do?
A: Anything! Whatever you think could be improved, fixed or rewritten, you’re welcome to do. We also have a list of Tasks that you could check out, just pick something that no one else has claimed.

Q: What’s with all the low quality jpgs?
A: For the time being, we’re using them just to keep the size of the repository down a bit, but sometime soon we’ll switch back to the original high quality images.

Q: Who can I shout at about all this?!

A: Just reply on this thread :slight_smile: I’ll read everything. There’s also the bf-docboard mailing list, as well as the project page which shows who the administrators and section owners are. We also hang out on the #blenderwiki channel on IRC.

I’m in. I started getting the tools I need… however… in the SVN installation section, it says:

  • Once the installation has finished, create a new folder that will contain everything related to the Blender Manual. In this guide we’ll use C:\blender_docs.
  • Open the new folder, right click and choose SVN Checkout… from the context menu.
  • In the URL of repository field, enter: https://svn.blender.org/svnroot/bf-manual/trunk/blender_docs.
  • In the Checkout directory field, enter: C:</b>.

Why is it suggested to change this to the drive’s root directory instead of using <drive>:/blender_docs? I followed the directions with suspicion and now I have a bunch of checked out folders in my drive’s root. Could the last step in these instructions be changed? I don’t think there would be a good reason to do this, but if I am mistaken, please let me know. See my mess below.

That said, I will be glad to contribute positively to this initiative. :slight_smile: Thanks for this Greg (and others) :slight_smile:

Attachments


Ah yep, you’re right. Checkout directory should be “C:\blender_docs”. I’ve updated the install doc, the change should go live in a few hours.

Is the more developer oriented stuff being transferred over also? I’m mostly referring to instructions on building from source. I noticed in the OpenSUSE instructions, there was one place where it said to use apt-get. Something makes me think that isn’t exactly accessible on OpenSUSE.

Nope, this manual is purely for using Blender, not for building it or any other development related stuffs (that’ll all remain on the wiki)

When you say “official,” is this coming from Blender Foundation?

OK. I might want to pitch in eventually, but I think I should probably get a bit more experience first.

Yep, Blender Foundation has hired me for three months to coordinate this project (announcement)

I will see about signing up to help when I get home, looks like a lot of fun!

I understand that this decision is already made, but why not stick with the Wiki format if you expect normal users to contribute to the manual? If Wiki format is good enough for “all of human knowledge”, what makes the blender manual different? Too much heirarchy in topics maybe? (I’m guessing)

Overall I think the manual could be quite good if regular, experienced users could simply update things here and there as they have a chance. Having to install special software is going to stop most people that would otherwise have contributed a little. Assigning a whole section to a volunteer will result in boom-bust cycles of completeness and freshness. When that person has time to contribute, they will… but since they aren’t paid, that won’t be forever.

@Kemmler, RestructuredText (RST) isn’t significantly different from MediaWiki markup - in compexity and the general concepts.

The Blender manual is different from wikipedia in that its can be seen as a single document/book which can be kept valid, up to date and shouldn’t organically grow into thousands of unrelated pages of varying quality.

Seeing that the StackExchange network uses markdown with 100,000’s of active users, I don’t think having to use a different markup is really a blocker.

Just had a look at the manual and my first impression is, wow, a nice improvement. I think it will be worth the effort and I like the idea of it becoming more standard in quality.

Well, let me give this a try.

I would love to help. I write user manuals for satellites and spacecraft, although I am not sure whether I know enough about Blender to help much.

@gregzaal,

looks great…easier to read, nice format, better navigation.

Is it possible to download the whole manual to use offline
even if you aren’t an editor?

Any chance it will be put in PDF so we could print the entire
or parts of the manual, not just pages?

BTW, good to have plenty of “white space”, but suggest the
right margin be the same width as the nav on the left,
and a shade darker for contrast with the center background. :slight_smile:


Yep! That’s one of the main advantages here - the whole manual can be downloaded as html, or pdf. At the moment no one has yet made such packages for you to download, but it’ll be done eventually (probably with the 2.74 release)

Great, thanks Greg! :slight_smile:

Where should we make suggestions for it?

If we can download the whole thing, then I imagine we can use the CSS
to adjust margins, color scheme, fonts, etc to our liking like we can Themes
in Prefs for Blender. Awesome. :wink:

Just subscribe to the bf-docboard mailing list, which will then allow you to send an email to [email protected] for us to discuss your suggestions :slight_smile:

All I can recommend Greg, as you and others are updating this, is to think application based. It’s almost like Marketing 101 features and benefits…

The manual always covers the “features” well, by giving overly complex descriptions of each and every button in technical jargon. What it does a terrible job at, is telling me why, when, and what type of applications it should be used for. The manual needs to think more like an artist.

We’ve discussed this a bit - we really want to write the manual from a practical perspective (explaining why a feature exists and where you might use it in a particular workflow), not just simply state what each button and slider does (although that is also very useful).