You're blocking ads, which pay for BlenderNation. Read about other ways to support us.

Dynamic Documentation!

38

codeDuring the Blender Conference there was a heated discussion on the topic of Blender documentation. Wray Bowling now reports on a new 2.5 feature that was recently added to easily access documentation for any user interface feature.

Wray writes:

Look! Right clicking buttons to see documentation got added! For the moment it only links to the python method, which isn't very useful to an artist, but this is a good start. At least it has the potential to be linked to a user's manual of sorts as the 2.5 project moves forward. This is now trunk, so any new build should have it.

blenderdocs

About Author

Bart Veldhuizen

I have a LONG history with Blender - I wrote some of the earliest Blender tutorials, worked for Not a Number and helped run the crowdfunding campaign that open sourced Blender (the first one on the internet!). I founded BlenderNation in 2006 and have been editing it every single day since then ;-) I also run the Blender Artists forum and I'm Head of Community at Sketchfab.

38 Comments

  1. This look really nice! But i guess the manual and the documentation is always the hardest part in such a big project. Good luck, because this could be great feature.
    best wishes

  2. It's awesome, right? I don't know who did it, but I'm sure they were sitting in that room when the debate happened. All I did was speak up and say "Processing has this feature and it's awesome. There's really no excuse not to have it" and so on. The news I got from Graphicall's twitter feed of all things. It doesn't report who did it, just that it *happened*. So, it would seem that live in-person debates among coders actually gets things done in less than a day. That's kind of *scary*. Maybe see who commited revision 24103 to find the exact person that gave us this.

  3. that's a very good idea! if the manual also came with Blender, it would help too. I've had trouble finding it, apart from the actual Manual on Blender.org

    It would certainly help new users learn what everything does.

    MeshWeaver

  4. rgdfhdfhdryerztetz on

    It certainly is a very useful feature.
    Must have this in Blender 2.50!!!!

    Would like a variation: a special button that when clicking.
    Enables the document things to be shown after right-clicking.

    Anyway, OpenOffice.org has some variant on this feature.
    (Go to top menu bar. Click Help>What is this? and hover over a few buttons.)

  5. Excellent!

    Will "View Docs" and "Edit Docs" link to a Wiki?

    If so, this can be a great way to encourage documentation help. It would also be nice to cache documentation locally too. (for the internet connection challenged.)

  6. Great feature!

    Still I think there should be a big button to "Beginner Tutorials" on the blender,org frontpage.
    I heard many people on forums that just couldn't find the "Education" link and the tutorials there are incomplete, links are broken etc.

  7. A nice move on helping documenting everything, would be get all information trough a page, xml format, that feeds both wiki and blender. My sugestion would be, let the users add they're input directly after right clicking (as a propousal ), in case the specific tool hasn't any information you can add your own; Other users would have it available, and could actually edit it; There could be supervisiong and revision on this; It's truth that, if everyone may put their effort in just one click, documentaiton will be filled in no time;

    So, basicly, you'd get an unlimited database with several and diferent inputs; How would this work ? Well, if the popup wish explains the tool, has small icons telling you about how accurate or how "aproved" is the explanation, there would be no problem!

    When I said xml format, it's because you can have infinite ID's predefined for inifinite positions on the Blender interface; So, all you had to do is name it and describe it! Any one could contribute in no time!

    About xml, feeding both wiki and blender, yeah, wiki could have the "under development" docs, or the oficial docs, or whatever, but in the bottom, there's the user input (allways supervised by others:: Supose that you needed 1000 approvals from other Blender Users, to be listed there).

    Just one point I think is important, is that, in case you didnt had any "tip", "documentaiton", or "description" for the specific tool, you can add your own like I said, but it's going be available with a warning message or Icon, to be revised by other users. Anyone could test if truth and give one point or approval.

    Is this making sense ? I dont know, but this is sounding good to me :) Oh yeah, this will need internet, but you can download all the oficial docs plus current "approved" user input!

    Isn't Wikipedia something like this ? Dont you think is good ? Isn't it truth, and usefull ? how ofter have you find something untruth there ? I never did, I allways find it very good!

  8. Campbell Barton (ideasman42) on

    Hey Bart, Mindrones and Myself worked on this (me on the blender side, him on the web side)
    Also worth posting this link since this is where edited docstrings go

    http://www.mindrones.com/blender/svn/

    Next we need a way to automatically download approved docstrings and apply as a patch into blenders C & Python code, should not be so hard. :D

    Also worth noting is that links to an API reference, not a manual, we will need some way to cross reference this in both directions.

    If all goes well we can auto document panels, headers, spaces too. as well as automatic screenshots of of the UI... but good to start small!

    Otherwise if it doesnt work out I can ofcourse remove it altogether.

  9. @m.ardito

    thanks a lot! been looking for a pdf version.

    MeshWeaver

    a minute later - ok, having trouble downloading it. do i need an account on that site so the button shows up? HELPPP!!!! ;-)

  10. wait, why does the time on my post say 1:13a.m. tomorrow?!?

    sorry for double posting, by the way.

    MeshWeaver

    update - ok, sorry, just found the download button. wasn't really obvious
    thanks!

  11. @MeshWeaver Maybe you live in another time zone as blendernation and the time stamps are not adapted to the local time zone of the visitors?

  12. This is nice! One small suggestion. How about adding some video tutorials and package them together with blender on how to move around. Some like what maya has.

  13. Will there be a search feature? The best thing in the world would be a full-text search feature that searched both the text of the docs and the text of all the buttons, menus and labels and presented you with a list of search results, each of which would each pop up (or make visible or call to the foreground) the UI element that they reference when you clicked on them.

  14. @MeshWeaver, @panzi: you're correct - we're using Dutch time (GMT+1). As the site is heavily cached, I won't be able to auto-adjust the time for each user..

  15. Not sure about this. Have to see it I guess. I also think it depends on value and clarity of the information it has to offer, otherwise it would be of little or no use. Makes me think of those opaque and misspelled manuals that sometimes comes with the appliances.

  16. I think it would be worthwhile for the Blender coders to look at the music sequencing program FL Studio 9 (http://flstudio.image-line.com/index.html). It's available as a fully working (save disabled) demo download. That program has a little window at the top left of the screen, just below the menu bar, that is *always* showing you a description of whatever control the mouse is hovering over, and even gives you the current value of a control (for control knobs, sliders, etc.).

    If that could be incorporated into Blender as a new 'Help window', new users could keep a thin help window somewhere on their screen layout, giving them an instant one line description of every control in sight!

  17. As one of the early adopters/supporters of Blender I still like to keep a printed book in my hands with an (thouroghly done) index in the back and a lot of (coloured) pix sprinkled throughout :) ...
    Something like the "Official Blender 2.3" of No Starch Press (who was missing somewhat on the two topics just mentioned), but with an .pdf version cross-searchable by computer delivered on disk.

    I'm ready to shell out 50 bucks (euros)in advance by subscription for such a project and I think the Blender foundation should give it a try - perhaps as a Wikibook under the Creative Commons licence.

    The book would appear also in local bookstores and could be shown to friends to make them gasp what's nowadays possible with Blender.

    And the upcoming Version 2.5 would be a good reason to tackle such a project, perhaps with Carsten Wartmann and Stefano Selleri as Editors and Marco heling out with the .pdf part.

  18. The next step would be to have the help in other languages than english...

    Because I have no problem with english, but I know a number of professionals who only speak one language... (yup, they are pro, but not internationally known pro)

  19. @wolfram
    +1, totally agree. i'll be glad to help for the pdf part, if you're speaking of me :)

    in the past the online wiki was a bit messed and also the 300+ links collection > pdf was difficult.
    now it should be better (user mindrones helped out putting a decent and tag in the html code to more easily catch just the content): when i have a simple workflow i'll post instruction on how to build those pdfs.
    i'ts just a bunch of PHP lines and a bit of post processing done with htmldoc. I am pretty sure it could be easily automated (on the wiki server for speed reasons) to have a "daily pdf wiki manual". or maybe on graphicall? :))

    just my 2c
    Marco

  20. Campbell Barton (ideasman42) Oct 29th, 2009 at 11:11 pm

    "Hey Bart, Mindrones and Myself worked on this (me on the blender side, him on the web side)"

    Thanks Guys!

Leave A Reply

To add a profile picture to your message, register your email address with Gravatar.com. To protect your email address, create an account on BlenderNation and log in when posting a message.