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,
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,

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