Hi Duarte, Sylvain, Alexandre, and Maren,
Thank you for your reply.
Duarte: I agree. We need to make volunteers engaged in the documentation. At least in the User Guide/UI doc.
Sylvain: Do you think the current wiki does not serve our needs for what particular reason? I would love to propose a separate repository -- or at least (one or two) folder(s) inside the main project -- for user guide doc and developer docs. I strongly believe we need to make these processes crystal clear and, as much as possible, give incentives for people to get involved in solving things they don't like (bugs or minor issues).
Alexandre: I think this is a great manual! The only setbacks, IMO, are the fact that we cannot download it in any format (HTML, PDF) and that we cannot translate it to other languages (even though this process can be difficult to engage people from time to time). I believe that this manual is a good model for us to follow. Good call.
Sylvain: I really enjoy the way Blender (https://docs.blender.org/ manual/en/dev/index.html) and Axialis (company that sells windows products) makes their help/tutorial files: http://www.axialis.com/ tutorials/tutorial-iw012.html
So what we're looking here is:
Git integration, SVG compatibility, Multiple output formats, Localization Collaboration Simple to use Markup language ...
Challenge accepted! :)
--Victor Westmann
2017-04-04 10:28 GMT-07:00 Maren Hachmann <maren@...325...>:
Hi Victor,
I've been thinking about rekindling that process, too, and have also already looked into a couple of different platforms - but none of them was able to fullfill all requirements, and I didn't want to build something home-made for this (can't maintain). Also, I currently lack the time to lead such an effort.
So, currently I can just confirm Sylvain and Alex:
- the Wiki is not a good place, it's going to be shut down in the long
run, sadly.
- there is a Booktype instance, with a book that needs to be updated,
which is hosted by flossmanuals, and can be used as a starting point. It could be edited any time, as far as I know.
Bryce suggested that we'd use the same system we use for the included tutorials, so we can also export to SVG. I don't really think that makes a lot of sense, though. It's great for 'interactive', hands-on tutorials, and it has the advantage of creating po files for easy translation, but it's difficult to edit the original files (and hard to compile the resulting documentation, as far as I understand).
Ideally, a manual platform would (in my opinion):
- use git for version control
- use reStructured Text for markup
- support translation (like: automatically mark translated pages as
outdated, mix translated and untranslated contents if there is only a partial translation)
- allow to include SVG images
- allow for easy collaboration
- supply an editor that makes it easy for non-coders to contribute
- export to a couple of different file formats, including html, pdf, and
one or more ebook formats
- allow for the files in the git repo to be also edited directly, and be
able to include the git repo in our own code repos.
- be open source (of course)
I believe gitbook already fulfills a lot of those requirements, but I don't want to do self-hosting, if that can be avoided (but still want to have the option to export everything and go to a different place with the contents).
But there's also Booktype, Readthedocs, pure Sphinx and a lot more.
Would you like to investigate the different available systems and put up a comparison between them? You can also collect info/user experiences from other open source projects.
Kind Regards, Maren
Am 04.04.2017 um 01:19 schrieb Victor Westmann:
Hi Maren and Duarte,
I know you guys are long time translators for the Inkscape project.
Do you guys know if the Inkscape project has some kind of official documentation/book/guide/wiki?
I stumbled upon www.gitbook.com http://www.gitbook.com and am using it for a couple of years now and I love it. Do you guys think this is feasible at some level?
Just wanted to share some new ideas and insights on possible improvements on the project.
Your thoughs and ideas are more than welcome!
--Victor Westmann