For many years we’ve been using MediaWiki for Synfig documentation.
And there were a lot of problems with that:
MediaWiki is hard to maintain (update version), it is affected by spambots and it is missing many features (like export of documentation to various formats).
Today we have a lot of other solutions and Sphinx docs (+ReadTheDocs) is looks like a common standard. (Our developer’s documentation is already in ReadTheDocs and sources are stored on GitHub).
Also, the documentation on MediaWiki is very much outdated.
So, I suggest to start with re-writing documentation of Synfig in ReadTheDocs format.
At the moment all pages are empty - I just created a basic structure, hope this will be a good starting point.
–
Please note, that we cannot blindly “copy-paste” docs from MediaWiki to GitHub repo because Mediawiki docs are licensed under CC-BY-SA. The latter makes it problematic to re-use, because requirement of this license is to track and list all previous contributors. This could be problematic in some situation, for example if we will want to publish a book based on manual. Considering that most of documentation is outdated anyway, I think that re-writing it completely under Public Domain license will be easier.
To assist with this process I suggest to apply for Google Season of Docs this year. ^___^
I just discussed this situation with old Synfig contributor (@d.j.a.y ) and came to a much better solution!
As I’ve said my main motivation for migrating into Public Domain license was this:
If we will copy content from MediaWiki, then we need to list every author for every page. I was afraid that this is going to be a LOT of work.
If someone will decide to publish new documentation (as pdf or book), then he will need to collect names of all people who contributed to new documentation (probably from GItHub commits), including contributors to old MediaWiki docs. Tricky!
Then I realized that the solution can be very simple.
It comes from the fact that according to CC-BY-SA license we have to credit all authors, but it doesn’t say that we should credit every author for every specific page.
Instead, we can have a dedicated page in our documentation, which is called “Authors”.
There we can put names of all people who contributed to old documentation on MediaWiki.
And this also solves problem number 2: all new authors also will be added on the same “Authors” page.
But isn’t it will be additional work to maintain this list? Maybe not! - we can put that burden onto shoulders of people who do contributions. I.e. if someone make edits, then he is responsible to adding himself into “Authors” page (we just need to clearly let people know about that).
If someone didn’t added himself to “Authors” - then this is probably his intention to stay non-credited contributor.
In this case we actually do not need migrating to Public Domain license - we can stick with CreativeCommons BY-SA. ^___^
I can contribute to doc writing. I had previously worked a little bit on updating the wiki on the old mediawiki site. So I am ready to help contribute again.
I have selected most critical pages to get core of documentation available in new place as soon as possible.
Please consider, that the conversion doesn’t takes into account internal links - only text formatting + images + external links are converted. I decided that we can parse all links as a “second stage”.
In this batch we have basic tutorials present, so I think we can change link on official website to new documentation (this way there are chances other people can start contributing on improving the docs).
In the meantime I will continue process of moving remaining pages from MediaWiki to Sphinx.
The “Documentation” link on the main Synfig website now points to new documentation. I hope this will allow us to attract more contributors to new documentation.
You need to fork the repo, do your modifications in RST format (similar to MarkDown), then send a pull request (PR).
Once the PR is accepted, the tutorial is available on ReadTheDocs.
For the edition, you can use for example Formiko
You can fork the documentation repository and try to edit on Github simple text editor, if you are confortable with RST/MarkDown. You will be able to see (barely) a preview of what you typed too.
I.e. if someone make edits, then he is responsible to adding himself into “Authors” page (we just need to clearly let people know about that).
