Documentation: please help write the docs!

Software Natron
6

Hi, I find some difference in documentation and my experience
in doc: (page 588)
#Set the After Project Created/Loaded callbacks
NatronEngine.natron.setOnProjectCreatedCallback(“myCallback”)
but in my project works
NatronEngine.natron.setOnProjectCreatedCallback(“init.myCallback”)
and
next plaсe don’t remember the page but may be example for setup project that you shered some years ago:
def addFormats(app):
app.addFormat(“Urfin2 2130x870 1.0”)
app.addFormat(“Urfin 2100x858 1.0”)

def Project_Callback(app):
app.getProjectParam(‘autoPreviews’).setValue(False)
app.getProjectParam(‘outputFormat’).setValue(“Urfin2”)
app.getProjectParam(‘frameRate’).setValue(24)
app.getProjectParam(‘frameRange’).setValue(1, 0)
app.getProjectParam(‘frameRange’).setValue(30, 1)
app.getProjectParam(‘lockRange’).setValue(True)

I can help you with documentation, but I have few time. Can you write video about how correct clone repository, how change some thing in doc and how can i correct send you pull request?
I think it will be helpfull for many people
Thank you!

7

There is plenty about this subject already, including github’s own documentation. You can do it entirely in your web browser with githibs edit functionality.

8

thank you! It is a very simple
I add some pull request about init.py

1 Like
9

I would be happy to add a useful and perhaps huge contribution to the Natron documentation in terms of usability and enjoyability, albeit with a caveate or two.

I should explain that I am today a professional technical writer and digital media artist/developer with my own personal licence for the industry leading tech’ authoring software Madcap Flare ( I know - it is not OpenSource but it is awesome. At £1500 or so was not an insubstantial purchase… but it really is the dog’s bollocks ( a British expression one may have to Google - Anything described as bollocks is rubbish quality, a useless product, or a ridiculous claim - BUT conversely, if it is described as the Dog’s Bollocks, there is nothing better! ). For any interested I have included a fuller background at the end.

Anyway I digress! I am about to learn Natron and the documentation looks comprehensive but not particularly navigable or engaging; (it seems a feature of Opensource that UI and documentation tend to fall behind commercial offerings). I am totally up for taking that content and using the industry leading toolset of Madcap Flare to createa website not dissimilar to 3DS MAX Documentation

  • Caveate 1: I am unsure I have the time to maintain such a site if updates are large and frequent, but my understanding is that Natron development is sadly pretty much dead - without any sign of an emergent replacement. Is that correct? If so then any updates would be infrequent and I would be happy to accommodate them. Of course, this is a deliverable distinct from the open source docs as unfortunately what I would deliver is not directly editable. That said if this took off I can see a way to enable contributor edit, but it would incur me cost and is easy but not entirely “technically trivial”, but then we are not a “technically trivial” userbase!

  • Caveate 2: Natron development may be dead but how “Dead” is Natron in terms of continuing users? If the view is that the party is over and everyone is moving on, clearly there is no point my doing this. However, if there are still many committed users who intend to use it for some years if nothing else materializes… well then it is worth doing.

Who the hell is this and why does he feel he has something to offer?
Being new here and unknown, I should probably establish some credibility!
Back in the '70s, yep I am that old, I completed degrees in architecture before jumping from the architectural ship to focus on the pioneering days of CAD and after writing my own extensions to the Prime minicomputer system “GDS”, still extant in PC form as “MicroGDS”. I leapt again from architecture to a career in software houses, first into CGI with a long deceased but again pioneering French company Thomson Digital Image aka “TDI”.

In 1989 they created the longest ever CGI movie “1789” . Today you may feel you could blink and miss it, but in those days with Silicon Graphics machines considered the dog’s bollocks (but pitifully slow compared to almost consumer laptops today), the rule of thumb was a £1000 a second!

Then I jumped again, into VR with Superscape - yes VR was an '80s phenomenon. When I hear the media talking about FB etc. as “VR Pioneers it cracks me up.” - From there I worked in both serious military flight simulation and desktop stuff like MIcrosoft Flight Sim before joinging LEGO as a concept developer… Like I said “Quantum Leap” seems sedentary to me!

BUT then I jumped again to what is now relevant… the tech author focus.

Thoughts? Anyone feel this something useful?

Best regards to all you Natron Users,

Ian

1 Like
10

I’m not a Natron user, but I think it would be really short sighted to move the documentation into a proprietary format with an application that not many can afford, and with a person who can’t commit to keeping it up to date, should development pick up again.

I don’t mean that as a knock on you, @MeridianCreative, your offer is generous, but I don’t see it as a long term benefit to the community. That’s just my opinion though, I’m sure others will disagree.

Also Madcap Flare… I’m a DITA / oxygenXML guy myself

11

I totally see your view. I am not suggesting that the documentation is moved into a proprietary format but rather that if these are the products end of days, a parallel delivery is created that offers a superior format that will help documentation usablility for what at present seems a product that is still valued but is dead in the water in terms of onward development. I don’t mean to be unkind but in my 35 years in the industry I cannot think of a singe example of a product in a similar position that again rose like a phoenix out of the ashes.

Perhaps a better documentation site might encourage an onward future.

Ah well, it was offered. No turn unstoned and all that. I will create such a site for my own benefit, but I guess best never to publish its URL.

12

The great thing about Free Software is that projects don’t really die as long as there is a copy of the source available. Anybody can get that code and start working.

You are free to publish whatever you’d like, keeping in mind that Natron’s documentation is licensed CC-BY-SA 4.0 at the bottom of the docs page: Natron documentation — Natron 2.3.16 documentation

1 Like
13

Let’s break your proposal into its two parts: an offer to write more engaging documentation, and a proposal to use Madcap Flare to author it.

I don’t think anyone would have a negative reaction to an offer to improve documentation. You are correct that documentation tends to lag everything else with most FOSS projects.

However, I share @paperdigits’ concerns about the authoring tool. Combine these statements:

and it appears to be a legitimate concern that the site would be unmaintainable if you were not able to keep maintaining it yourself.

I’m not a Natron user, but in the relatively short time it’s been included in discuss.pixls.us there has been a fairly high volume of posts, so it appears there is a lot of interest.

Personally, I think your offer is very generous, and I think it would become that much more generous if you are willing to use a FOSS tool to author the content.

1 Like
14

Thanks for the feedback. My point is that if I felt a FOSS tool could deliver to the level that I can deliver in the Flare product I would never have spent £1500 on the Flare product and someone would already have delivered the kind of professional finished documentation in that FOSS tool. The fact they have not kinda proves the point.

I am in complete agreement that if the community anticipates Natron continuing to evolve in any substantial way, to mirror the FOSS delivered documentation in a superior form carries an overhead which I am uncertain I feel that generously committed to. If alternatively this really is the “end of days” for the onward development then I would have felt there to be merit.

As it is, I am clearly not with the consensus on this, so will just create it for my own use as I think it will help my Natron learning curve to do so. I wish I’d never posted the offer now to be honest! :-/

Ian

1 Like
16

Don’t be discouraged. Do what you think is best. There is nothing preventing you from doing this and sharing it, or not, on your own terms. What they are proposing is that using FLOSS authoring tools would help in the collaborative effort.

3 Likes
17

Just keep in mind that the Natron doc is written in one of the most easy to handle format: text files.
Everything which is not pure text (formatting, images, links, etc) is using reStructuredText .
I don’t think the community should move away from that.

For his tutorials (HSVTool, Vector graphics workflow, Alternative Matte Extraction), @Blackvfx2018 sent us Word files, which were very easily converted to RST (using the pandoc tool, available on all platforms). I then had to fix a few glitches, and voilà. These tutorials look very nice.

One thing we should definitely do ASAP is to use a more standard theme for the docs, eg: Read the Docs Sphinx Theme — Read the Docs Sphinx Theme 0.5.1 documentation

The current theme doesn’t even have a search box.

4 Likes
18

What is the problem with switching the theme. Should be done easily in one line. Or am I missing something?

19

I made my own readthedocs playground for the Natron docs. Here is what I am getting with sphinx_rtd_theme.

Could somebody take a look and confirm it seem ready to merge?

4 Likes
20

YES! thank you for that! Please file a pull request on github with these changes

3 Likes
21

@ivangretsky can you please file a PR? Pull requests · NatronGitHub/Natron · GitHub
Please do it on the RB-2.3 branch.

Thank you

22

Sorry for a delay. Was away from the computer I could do it from. Will try to do it ASAP.

23

Made a PR. Please feel free to comment there if anything goes wrong.

1 Like
24

Thanks Ivan! We now have a good-looking and searchable documentation!

3 Likes
25

I started to document the Compositing section in the User Guide.
I create a branch from the RB-2.3 branch, but I don’t understand this part of the documentation guide:

‘… give it a name like’ documentation-keying ‘if you are going to write the keying doc …’

Questions

  1. How can I name my fork on github (I currently working on Reformatting elements section)

  2. If I want to document many other Compositing subtopics, what is the simpler way?
    Rename every time my fork, when I edit different topics at the same time? It’s very uncomfortable and weird.

Thank you

1 Like
26

Are you using GitHub Desktop ?
The doc is confusing, but once you know, it’s simple.

  1. Fork natron repo to your repo.
  2. Make a branch from it and call it ‘natron-doc’ for example.
  3. Switch to that branch
  4. Make the changes you want.
  5. Make a pull request to R-B 2.3.
  6. Wait for request to be accepted or not.
1 Like