Being mainly a Blender user I can only say good things about Blender
manual. I think it is a Sphinx based system, and works quite well.
Then again I still feel its success mostly stems from the amount of work
and effort from the developers that went into building it, rather that
the platform itself.
I do like that the sphinx system allows (I believe) a searchable,
downloadable offline format for local use. Think packing the manual
along with the Inkscape release for local use.
On 04-04-2017 19:31, Victor Westmann wrote:
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
<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
<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 <ma...@goos-habermann.de
<mailto:ma...@goos-habermann.de>>:
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>
<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
>
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Inkscape-translator mailing list
Inkscape-translator@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/inkscape-translator
