Hi Everyone,
I've tried to read up and study and understand the info which Maren
presented. Because my understanding is extremely limited, I hesitate to offer
any comments at all. But for whatever it might be worth, here they
are....along
with a couple of questions.
First, one of your last comments:
> All of them would be FLOSS, have support for internal linking, allow to
insert images and allow editing via browser.
I think you're using "FLOSS" as a generic umbrella term, as opposed to
the FLOSS Manuals, right? Because a couple of the Cons are lack of wysiwyg,
which I've had the understanding Floss Manuals has (although I haven't seen it
yet). So you don't mean that Floss Manuals can be used for the writing, for
all
of them, and then exported out or transfered elsewhere for publishing, right?
Gitlab Wiki + X
It seems to me like the lack of a wysiwyg editor is the most limiting factor
(at
least for as much as I understand). I'm just thinking of people who might be
interested in joining the manual or documentation team. This is a good
non-coding opportunity for non-programmers, to contribute to the project. They
might be less likely to participate if they had to learn, even a simple
language
like Markdown, or whatever you call the code that wikis use.
Gitlab Editor + Sphinx / readthedocs
> - learning curve for admin (theming, plugins,...)
You must mean that someone else besides Martin would be the admin for the
manual
project? Or, as admin for the gitlab account, is there something about this
option that he would need to learn still?
All the pros for this option make it sound so good (at least what I can
understand). But still no wysiwyg editor. I still think that might scare away
some potential contributors.
Booktype
So far, this sounds like the best option to me.
Gitbook
The 5 contributor limit for free hosting sounds untennable to me.
So based on my feeble understanding of all this, I'd vote for Booktype.
All best,
brynn
-----Original Message-----
From: Maren Hachmann
Sent: Tuesday, May 02, 2017 5:59 PM
To: C R ; Inkscape Devel List ; Inkscape-Docs
Subject: Re: [Inkscape-devel] Any chance we can make some docs material?
(targeting the moon)
Hi,
sorry for the delay. I've been trying things out a bit, and I feel I
haven't seen enough yet, but I won't have time tomorrow, so posting
anyway now.
So, it seems that what we still need for a manual (any kind) is a
platform to create it (not only write, but also output to different
formats).
I have had a chance to look at 3 different platforms on my list, and I'm
trying to outline the pros and cons, as I perceive them, please add
yours to the list. There are many more platforms in existance (see also:
https://github.com/PharkMillups/beautiful-docs#generating-docs), and if
anyone here has some experience with them, please add.
*************
- Gitlab Wiki + X, as suggested by Martin.
WHAT: An online Wiki on gitlab with a source code editor, associated
with a gitlab project.
PROS:
- custom-made to suit the project's individual needs (no specifics yet)
- Preview functionality
CONS:
- only (limited set of) Markdown, RDoc or AsciiDoc
- limited formatting options, formatting not so much about 'roles'
of formatted text, but more about 'looks'
- the backend isn't written yet
- no option for branches via interface (so we could start writing
for trunk, and continue fixing for stable)
- no direct translation support
- support for the backend depends upon a single individual, no user
community
- no WYSIWYG editor
- no GUI access to git repo, for managing where to put uploaded
files etc.
- no GUI for undoing a change (like in a 'normal' Wiki), or looking
at a diff
EXAMPLE (frontend): https://gitlab.com/inkscape/inkscape-web/wikis/home
*************
- Gitlab Editor + Sphinx / readthedocs:
WHAT: A git repository with an online source code editor and
documentation update on readthedocs.org on save (i.e. commit).
PROS:
- available quickly (didn't know how it works exactly, but got it
all up and running with test content within an evening)
- uses git and reStructured Text
- allows to have branches, so devel version features can be
documented when they are coded
- supports translations (not entirely sure how, though, haven't
tested it yet, wanted to send this email instead. E.g. Django docs are
translated. Fallback to English if no translation of a document. I think
they use different branches.)
- free theming, separately for each output format
- free hosting, can also use our own domain name with
readthedocs.org, e.g. docs.inkscape.org
- after installing some programs, tool chain runs locally
- preview via gitlab editor or local editor
- same toolchain can be used for developer documentation (includes
code documentation from docstrings)
- extensible via plugins (haven't had a chance to take a closer look
yet or test any)
- I think it's possible to add a 'edit this page on gitlab' link to
each page, to get new contributors, even when using readthedocs.org (not
tested, but read that others did similar things)
- extremely wide range of export formats via plugins
- infinite hierarchy nesting
- syntax highlighting (e.g. for command line usage instructions, or
extension writers)
- video embedding (not tested)
CONS:
- learning curve for admin (theming, plugins,...)
- learning curve for editors (syntax, workflow)
- no WYSIWYG editor, only preview (incomplete, because doesn't
support all sphinx stuff)
EXAMPLE:
- repository:
https://gitlab.com/Moini/inkscape-extensions-multi-bool/tree/master/docs
- rendered documentation:
http://inkscape-multi-bool-extension.readthedocs.io/en/latest/index.html
*************
- Booktype:
WHAT: A web portal for creating books, hosted by friends of the Inkscape
project.
PROS:
- available right now, no further setup required
- best interface by far, easy and intuitive to use
- team functions, user roles, chat
- prevents concurrent editing
- wide range of export and import formats
- support for themes/settings for specific export formats (e.g.
different font sizes etc.)
- free hosting and maintenance via flossmanuals(fr)
- community of experienced documentors
CONS:
- confinement to django database for version control, more difficult
to get data out of it again for editing
- no direct translation support (make a copy of the book, copy
changes over after doing a comparison in the history)
- limited versioning support (only the latest one can be
edited)
- we'd need to ask someone to add CC-By-SA licence (currently, the
options I got were CC-By, GPL. I guess this would be quick and easy to
solve.)
EXAMPLE (rendered documentation):
https://www.flossmanualsfr.net/initiation-inkscape/
*************
All of them would be FLOSS, have support for internal linking, allow to
insert images and allow editing via browser.
*************
I wish it were possible to combine the ease of use of the booktype
frontend with the portability, branch support, sustainability and
versatility of the gitlab/sphinx/readthedocs backend...
(In German that's called the 'eierlegende Wollmilchsau' - egg-laying
wool- and milk-giving pig...)
For the sphinx option, I believe I'd be able to take on the first setup
and some of the tasks that come with customization and extending, as
well as basic maintenance. For Booktype, anyone of the documentation
writers could do that easily.
Regards,
Maren
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Inkscape-devel mailing list
inkscape-de...@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/inkscape-devel
------------------------------------------------------------------------------
Check out the vibrant tech community on one of the world's most
engaging tech sites, Slashdot.org! http://sdm.link/slashdot
_______________________________________________
Inkscape-docs mailing list
Inkscape-docs@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/inkscape-docs
