New documentation

Hi everyone!

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.

Here is a repository - https://github.com/synfig/synfig-docs
And here is a “rendered” documentation - https://synfig.readthedocs.io/en/latest/index.html

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. ^___^

3 Likes

Yes the documentation is really outdated. Would be happy to new documentation :smiley:

1 Like

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:

  1. 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.
  2. 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. :slight_smile: 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. ^___^

So, I have created this page with information about license and contributors - https://synfig.readthedocs.io/en/latest/about.html :slight_smile:

Okay, I did next steps:

  1. MediaWiki documentation now locked for editing to everyone, except of SysOps
  2. I have created a list of all pages and put them into Trello board to manage process of converting pages to new documentation - https://trello.com/b/H7E592gX/synfig-documentation-migration

Pending tasks:

  • Prepare submission for Google Season of Docs (deadline is 4th of May!)
  • Write instructions how to move pages from old docs to new
  • Add notifications for people who contributing to new documentation on GitHub (use EasyCLA?)

Okay, I have made submission. If someone wants to participate as mentor - please contact me before May 4th, 20:00 UTC. :slight_smile:

Also, I have crafted a blog announcement, which I plan to publish tomorrow.
Here is a draft text, I put it in GitHub repo - https://github.com/synfig/synfig-blog/blob/master/google-season-of-docs-announcement.md
If you have any corrections or improvements for the text - please do not hesitate to submit them via PR. :slight_smile:

Pending tasks:

  • Write instructions how to move pages from old docs to new
  • Add notifications for people who contributing to new documentation on GitHub (use EasyCLA?)
  • Add notification banner to old wiki, which notifies about migration to ReadTheDocs.
2 Likes

Finally! Thanks for getting this started.

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.

1 Like

Awesome! Happy to see you in team! :slight_smile:

Quick news: Our submission for Google Season of Docs wasn’t accepted.
In any case, we will continue working on new documentation. :slight_smile:

2 Likes