Documentation: please help write the docs!

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.

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: https://natron.readthedocs.io/en/rb-2.3/

1 Like

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

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

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.

2 Likes

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: https://sphinx-rtd-theme.readthedocs.io/en/stable/

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

4 Likes

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

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

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

3 Likes

@ivangretsky can you please file a PR? https://github.com/NatronGitHub/Natron/pulls
Please do it on the RB-2.3 branch.

Thank you

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

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

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

3 Likes

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

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

Ok, thank you for your help!

And one detail that may not clear in the current doc: do not try to touch the rst files for the plugins documentation (the _group* files or anything in the plugins directory) or the _prefs.rst file, because they are generated automatically

I just made more clear in the documentation which files can be edited and which cannot (should be updated on https://natron.readthedocs.io/en/rb-2.3/guide/tutorials-writedoc.html within one hour).

You can also improve the documentation on how to write documentation, of course!

1 Like

Great! Thank you for quick update!

I fixed many links in the docs, especially the python part of it.

3 Likes