I started transferring documentation from old wiki to readthedocs. First candidate for transferring is Convert page: Convert - Synfig Animation Studio
First, I gotta complain about the choice of documentation system. Synfig now uses Sphinx and it’s not exactly very easy to set up for non-tech savvy people. You need to install Python, modules, git (learn the git workflow), learn basics of RST (documentation is in reStructuredText, not Markdown or HTML) just to make a small change.
Basically, the learning curve is much steeper for people who want to contribute to documentation than it was with the old wiki. So I doubt that switching documentation system was a good choice… There’s a difference between code that requires knowledge about computer’s inner-working so you can expect that programmer will easily learn additional instruments such as git and documentation that a simple user should be able to improve without having to jump through various hoops.
Anyway… here’s the commit with initial structure for Converters page: Add initial structure for Converters page by Svarov-RZM · Pull Request #73 · synfig/synfig-docs · GitHub
I will start slowly rewriting stuff since I cannot just copy it from the old wiki (the licence is different) and will report the progress here. Please note that I am not native English speaker (I am Russian) so feel free to correct my writing when I get something done.
readthedocs, Sphinx, Python, git, RST (documentation is in reStructuredText, not Markdown or HTML)
it’s not exactly very easy to set up for non-tech savvy people
What surprised me the most when this choice was made is that Github offers natively the possibility to provide a Wiki.
And even a (static pages) project website that is compatible with markdown, in Jekyll or any other SSG like Hugo.
ReadTheDocs is an external service but “tied” to Github anyway …
Also RST comes from the world of Python’s docs
Here is a list of the main differences between MD and RST
You can also try an online editor, import the original, modify and copy-paste the whole ^^
Just reviewed the license of the old wiki, as stated on the bottom:
Content of this Synfig Studio Documentation Wiki is available under the terms of Creative Commons Attribution-Share Alike 3.0 license.
By contributing here you agree that the same license will be applied to your writing.
If you do not want your writing to be edited mercilessly and redistributed at will, then do not submit it to this wiki.
You are also promising us that you wrote this yourself, or copied it from a public domain or similar free resource.
Do not submit copyrighted work without permission!
In other terms:
The content belongs to Synfig’s organization as CC-BY-SA
The individual authors accept to give their work to the organization which can also edit/remove and redistribute at will (the BY is now the organization and not the individual author).
Even though they are keeping morally the copyright on it, unless it is written somewhere in the content something like “tutorial made by xxx” for the attribution, no one is checking the changes one by one in order to discover who made it.
The individual has the responsibility to have created original content or used only source without copyright holders
I would say that doing the work of copy-paste from the Wiki to the new documentation doesn’t make it change of copyright holder (the organization).
Also, the copyright holder can change the license at will at some point for the future work on it (someone can have obtained the content under the CC-BY-SA and still apply it for himself).
@BobSynfig Nice analysis. After reading your post, I do think it has no problems to do it.
But I agree with Svarov: the ReadTheDocs is bad for regular public contribution: not easy to see what you write/are writing, not that easy to contribute due to the strange syntax, the words and expression like Pull Request, etc.
(btw, Svarov, you can create and edit some text files in the web interface of Github itself)
What about creating a website that handle it?
regular MarkDown for writing with WYSIWG (I imagine something like two “columns” - user types on the left panel and see the rendered result on the right panel
Optionally, user can see the current diff to original document (if s/he is editing one)
The action “save” the document, behind the scenes, creates a “merge request” to a git repository
Reviewers can approve or not - maybe some users don’t need to be reviewed. Once approved, it does merge the user contribution
Is there something like this? Opensource and free?
Well, even if it’s OK to copy documentation from old wiki, I don’t really have problem with rewriting it either. The wiki was always a bit of a mess, so rewriting some pages may actually be beneficial.
It’s nice to know, but I need the ability to view the rendered result, so I can check the formatting of the page, so nothing is misaligned after my changes. It’s good for small corrections I guess, like grammatical errors.
Ehh, it will make things easier of course, but it’s not the main issue. The biggest problem for me is that I can’t even share my progress with people, we cannot collaborate in any meaningful way.
For example, a week ago I rewrote an Overview page for Converters section, here is the PR: [Converters->Overview] First draft by Svarov-RZM · Pull Request #75 · synfig/synfig-docs · GitHub
And it just hangs there in PRs… Until it gets merged I cannot share it with you all because it doesn’t have intended formatting. What am I suppose to do? Post a link to a diff section? It’s not rendered documentation, it’s not how it will look in HTML form. So I am just waiting until it gets merged, I cannot move on to next page because I don’t know if my writing is good enough…
We cannot just move to something different, we need to collaboratively choose where to store official documentation, otherwise we will spread the documentation across three places: old wiki, readthedocs, github wiki or whatever. It’s very hard to discuss this without having morevnaproject involved…
