Re: [Inkscape-devel] Any chance we can make some docs material? (targeting the moon)

29 Apr 2017

      Hi all,
oh, wow, I've just been offline for a couple of hours - wouldn't have
expected that, if finally someone gives the 'go' for a manual, there
would be such a huge echo (we've been discussing this on and off for a
/very/ long time already). That's just cool :D
Just some comments to various things that were mentioned:
@CR: I think Scribus is a great tool for making the kind of graphical,
polished, sellable, printable, book-with-columns-like structure which
was linked in that very first link. For something that is really nice to
look at, and is fun to read and touch.
I also think this is not the same as a manual, which should be quick to
browse, quick to grasp, with lots of interlinks, with a file format
suitable for version control (well, yes, Scribus is xml, I've been told,
so it would be /readable/ - but those diffs are really ugly), with
out-of-the-box automated generation of online versions of a manual - as
can be done with tools like sphinx/readthedocs, doctype, and other tools
specifically tailored for open source documentation + gitlab CI.
You can take a look at the link from Victor's message to the mailing
list, if you would like to know more:
https://sourceforge.net/p/inkscape/mailman/message/35773618/
Even the booktype server of flossmanuals works with automation.
Using one of those would also have the advantage that, once set up, this
system could be used for both developer as well as user documentation
(as Victor wrote in his post - and I agree with him).
As for the attribution, I think especially the book-like structure would
profit from it, as I believe that artists may be more likely to
contribute their drawings if those are - at least - credited to them.
Also, it would be good if things like the keyboard+mouse reference and
other stuff we already have could be included. It's faster that way.
Faster also means: quicker rewards. This is good if you want to have
many contributors. Also, crediting people for their work is just
something that makes them more willing to contribute (as stated above).
CC-By would lose that, after the first iteration, as far as my
understanding of the licence goes.
Some of the people involved in flossmanualsfr are also long-time
contributors to and developers of Inkscape, so that's the relation.
The other, English, outdated, manual that you linked to, has been
written by many of the 'old hands' in the Inkscape community - some of
whom have moved on, and some of whom are still involved.
@doctormo: "FLOSS Manuals utilise la licence libre GPL pour l'ensemble
de ses travaux." - translates to: all manuals on flossmanuals are under
the GPL (don't ask which version, doesn't say there on that page.
(https://www.flossmanualsfr.net/faq-floss-manuals-francophone/ch011_quest-ce-...).
@Brynn: if you want to help with the translation of that 'intro' book,
you could, for example, make corresponding screenshots for it, of the
English version. You could also get an account on that site, and explain
to others who speak both French and English how it works, and what they
would need to do to join. Or write a news article asking for translators
who would like to help.
Also, you could add a 'Credits' page at the end, which seems to be
missing still.
And, of course, you can proofread and edit. Sylvain has already
translated quite a bit.
The NC licence is maybe a bit overprotective, but I'm all for crediting
and having a manual be available for anyone who needs it. I personally
wouldn't mind if someone prints and sells it and makes money with that.
As long as that is not the only source of the book/manual, this doesn't
cause me any worries.
I think google translate might cause more issues than solve them - but
it has been getting better... I personally find that correcting a badly
messed-up text which already gives me some 'scheme' tends to give worse
translations, than when there is no scaffolding. It's because the
machine translation is kind of giving the direction. It may be faster,
but the translation sounds less natural.
@jazzynico or Elisa: Can you tell us the specific flossmanuals licence?
GPLv2 or 3? Or, if not specified, do you know which version it would use
then, legally? Does Booktype use any kind of version control that is
compatible with git? What is the source file format?
@Miguel: yes, we're discussing those workarounds (and many others) on
the forums on a regular basis. It would certainly be cool if someone
could compile the 'Tips + Tricks' (sounds better than workarounds?) to
make up a separate section in the manual, or even a separate manual by
its own.
(sorry for the long post, there was a lot to reply to :D)
Maren
Am 29.04.2017 um 21:22 schrieb C R:
...
Also this: http://write.flossmanuals.net/inkscape/
On Sat, Apr 29, 2017 at 8:04 PM, C R <cajhne@...400...> wrote:
...
...
...
Books done in Scribus can be "published" in a variety of ways,....
Yes, I understand that.  But I thought Victor was talking about a hardback
book, like at the link he provided.  That kind of book is hard to get
published, unless you have some prior agreement with a publisher.  At least
that's my understanding.
We can self-publish, but we'd have to order a thousand copies, which
would take some startup funds. I don't think hardback would be
necessary.
In fact, I don't imagine printing is necessary. We could render out a
nice illustration of the book, with "ebook" under it, and people can
enjoy the aesthetic without downing a bunch of trees to make physical
copies of the manual. Virtual copies have great things like
hyperlinks, and text search capabilities. So there are more benefits
to having a digital copy anyway.
...
Somewhere in this thread was some discussion about licensing.  If this is to
be a hardback book (old fashioned way of publishing) *to me* it makes more
sense to carry a copyright.
The only requirement for a published physical book is an isbn number
(for product catalog, and inventory purposes). The license of the
book, as I understand it, is left completely open to the authors. We
would not have this published by a company interested in owning the
copyright, of course.
...
As far as I understand, publishers take a cut
of sales.  And if it's a public domain content, there wouldn't be many
sales.  It seems like it would make it even harder to find a publisher.
A publisher isn't necessary for this project, assuming the content is
what's important. If we want book sales out of this, that's the point
where it will become an issue.
...
I don't know, maybe I'm old and old fashioned.  But the FLOSS manual, on the
other hand, certainly should be either public domain, or CC-BY-NC-SA might
be better.  Whatever it needs to have, to allow the community to edit.
All I can guarantee is that my contributions will be public domain. :)
...
This is probably a bad idea.  But I'm trying to think outside the box.  What
if I (or other non-French-speaker) took one of the French pages, and sent it
through the public google and/or bing translators.  I know those are far
from perfect.  (Sooooo far!)  But since I know Inkscape, it seems like it
would give me enough of a clue what it's about, to be able to write it
properly in English.
Well, translation plus proof-reading is fine I'd think. It's not like
the subject matter would be alien to you. :) Fact is, you could easily
re-write from scratch the missing sections in English, then we would
be able to use it in our own "official" Inkscape manual too.
...
Then maybe the translators can proof read it, to make sure something
important wasn't missed?  Proof reading would seem to be much less
time-consuming for them.
Would that work??
All best,
brynn
As I understand it, the Inkscape Project has nothing to do with
flossmanuals, so perhaps it's beyond the scope of this project.
...
-----Original Message----- From: C R
Sent: Saturday, April 29, 2017 9:54 AM
To: brynn
Cc: Inkscape-Docs ; Inkscape Devel List ; Maren Hachmann ; Victor Westmann
Subject: Re: [Inkscape-devel] Any chance we can make some docs material?
(targeting the moon)
...
I don't mean to slow anyone's roll here.  But wouldn't it make more sense
to put
any kind of energy towards documentation into the much discussed, direly
needed,
user-focused, step by step manual?  Rather than starting from scratch on a
whole
different kind of project?
Yea, this actually makes a lot of sense as a first step.
...
There are many books out there already, which amount to a series of
tutorials.
It's not a bad thing.  I just think this kind of project is better suited
for a
single author, or maybe a small team.  And I think the project needs the
manual
much, more more than the community needs another book of tutorials.
I agree. I think the book could be a lot of things in one. But I agree
with finishing what we already have before starting something new.
...
As far as I understand, all that's needed is an English translation
of...well
can't find a link to the French version.  Here's a link to whatever has
been
translated already:
https://fr.flossmanuals.net/start-with-inkscape/introduction/
I can't help with translation, unfortunately. But I'd like to see this
finished. So +1 for the suggestion.
...
Once we have the translation, we'll be off and running to update and
finish it!
By the way, is there anything those of us who can't translate, can do, to
help
the translators?
I volunteer to help this effort in what ways are needed.
...
And won't such a new book of tutorials have to be published?  A big
obstacle to
writing any book is getting it published.  You almost have to have an
invitation
from a publisher to be certain a book will get published.  Or publish it
yourself, which is not easy eitiher.
Books done in Scribus can be "published" in a variety of ways, opened
in browsers, laptops, eReaders, or just printed out. We could sell
printed copies along with other Inkscape stuff. Maybe copies signed by
members of the project would be kinda cool. No idea what the market is
for it, but the idea that we could do all of these at once is
attractive, and why I recommend Scribus.
-C
...
Just my opinion  :-)
brynn
-----Original Message-----
From: Maren Hachmann
Sent: Friday, April 28, 2017 4:01 PM
To: Inkscape-Docs ; Inkscape Devel List
Subject: Re: [Inkscape-devel] Any chance we can make some docs material?
(targeting the moon)
Would it make sense to use gitlab's new subgroups feature for this?
The inkscape-docs team could be a sub-team of Inkscape, that way. There
are only 4 members as of now, so changing wouldn't be so difficult as it
might be later on.
Maren
...
Am 28.04.2017 um 16:14 schrieb Martin Owens:
...
On Fri, 2017-04-28 at 12:39 +0100, C R wrote:
>
> I'd love to quit my job and just do docs. :) Unfortunately, that's
> what it would probably take to get docs going to the extent we'd
> like.
> It's been discussed before, but never gone anywhere because of lack
> of time/hands involved.
>
> Yes, we should use Scribus to do it. In fact, it should probably be a
> github project to attract contributors. This way we can patch what
> needs to be patched when stuff changes in subsequent releases.
Sounds like you have a solid step one Chris.
Here's the inkscape-docs group on gitlab, EVERYONE should join, there
should be a button to join:
https://gitlab.com/inkscape-docs
And here's the new book/manual/docs project where files can be put:
https://gitlab.com/inkscape/manuals
I recommend using the wiki attached to the project to plan the
adventure slowly. Add a bit at a time and don't rush to have something
"complete" but have something small produced.
Best Regards, Martin Owens

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-devel@lists.sourceforge.net
https://lists.sourceforge.net/lists/listinfo/inkscape-devel