Re: [Inkscape-docs] [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
Hi Maren and all, I appreciate your research into, and review of.....well I don't even understand what this is.
Could someone give me a simple explanation? I'm still thinking "translate French FLOSS manual" and then update and expand the translation as a FLOSS doc. I don't think we should abandon that, after all the work that Sylvain and Hineringi have put in. Not to forget the French team too.
Are we moving away from FLOSS because of its license? This is a fine point which I don't get. Could someone make this simple for me, too?
Thanks, 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-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Am 05.05.2017 um 16:04 schrieb brynn:
Hi Maren and all, I appreciate your research into, and review of.....well I don't even understand what this is.
Could someone give me a simple explanation? I'm still thinking"translate French FLOSS manual" and then update and expand the translation as a FLOSS doc. I don't think we should abandon that, after all the work that Sylvain and Hineringi have put in. Not to forget the French team too.
- Yes, that would be one of the options (the last one in the list I posted). But there are more ways to write documentation, especially if you're dealing with maintaining different versions of the software (and thus the manual) in parallel, and different languages.
I'm not suggesting abandoning that book. On the contrary, yesterday I've translated one more short chapter (and found the editor to be less comfortable than the one we have on our django website, esp. for inserting files/pictures), and I've just sent out a private email to Hinerangi, because I think she might not be listening here currently, but we'd need her consent for a licence change from GPL (which is generally deemed unsuitable for documentation) to a CC licence.
But it would be entirely possible to manage the book's contents on a different website, using a different system.
Are we moving away from FLOSS because of its license? This is afine point which I don't get. Could someone make this simple for me, too?
- No, the licence discussion is not related to the discussion about finding a suitable editing platform.
The website where the book lives currently, flossmanualsfr.com, is a fine website for writing books. However, it lacks some features that would be very useful for us, e.g. customization, versioning with undo, support for different software versions and languages.
Likewise, the other suggested platforms lack features (especially in contributor-usability), and there exist other platforms that people may know about.
I was hoping to get some input on what is more important to people. To me as someone who would probably be working on the more organizational side, the frontend doesn't matter so much. I'm used to doing my editing in a text editor, and to use a preview. I'm also used to installing/running software on my computer, for testing my edits locally (which wouldn't be mandatory, though - a website that allows to edit the texts is available for each of the items on the list). What matters to me is that it is easy to have multiple versions and translations available, and to be able to automate the process. Also, to allow people who aren't involved in the project yet to do quick edits and request their inclusion into the manual. And to have a highly customizable output - concerning output formats (ebook formats, html, pdf, maybe even an 'app'), and styling of those (which I think CR might enjoy).
But I know that many of the possible editors might be afraid of the gitlab workflow, and I wanted people to be able to take a look at the different options.
I've got one more platform to add to the list (as 'looked at, I'd discourage usage'):
***************
Gitbook
WHAT: node.js-based modern toolchain to build docs from markdown/Asciidoc (locally installable version available) - disclaimer: didn't test, only read.
PROS: - comes with an editor that is graphical, and integrates support for the version control part, so users do not need to worry about learning git or finding their way around the git**b user interfaces. - includes support for multiple language versions - customizable templates / themes - free hosting available
CONS: - the above mentioned editor is proprietary. There exists a no-longer-in-development open source legacy version. - free hosting limited to 5 contributors - all in all (if you take away the limited hosting and the non-free editor) similar to the readthedocs version, but building on a system I wouldn't be able to deal with, userbase / maturity is probably a lot smaller/less than the one of readthedocs/sphinx.
Homepage: https://www.gitbook.com/ Source repo example: https://github.com/GitbookIO/gitbook/tree/master/docs Example web page: https://www.gitbook.com/book/frontendmasters/front-end-handbook/details
****************
Kind Regards, Maren
Thanks, 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-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Oh, thank you so much for explaining it! Well I'll get subscribed on FLOSS and give the editing a test.
And I'll also read through your notes now, and share comments about the other options, if I have any that are different from yours.
However, it lacks some features that
would be very useful for us, e.g. customization, versioning with undo, support for different software versions and languages.
Versioning? I thought the whole point of a manual which the community can maintain, would be to have A manual, which is theoretically always being edited (although more around Inkscape release times) and always up to date. Do you mean that if people wanted to print as an ebook or download PDF, those would have versions?
Languages? It seems like FLOSS does provide support for, well, at least 2 different languages, case in point, the French version which is being translated. Do you mean some kind of automatic translation?
Thanks again, brynn
-----Original Message----- From: Maren Hachmann Sent: Sunday, May 07, 2017 2:54 PM To: brynn ; C R ; Inkscape Devel List ; Inkscape-Docs Subject: Re: [Inkscape-devel] Any chance we can make some docs material? (targeting the moon)
Am 05.05.2017 um 16:04 schrieb brynn:
Hi Maren and all, I appreciate your research into, and review of.....well I don't even understand what this is.
Could someone give me a simple explanation? I'm still thinking"translate French FLOSS manual" and then update and expand the translation as a FLOSS doc. I don't think we should abandon that, after all the work that Sylvain and Hineringi have put in. Not to forget the French team too.
- Yes, that would be one of the options (the last one in the list I posted). But there are more ways to write documentation, especially if you're dealing with maintaining different versions of the software (and thus the manual) in parallel, and different languages.
I'm not suggesting abandoning that book. On the contrary, yesterday I've translated one more short chapter (and found the editor to be less comfortable than the one we have on our django website, esp. for inserting files/pictures), and I've just sent out a private email to Hinerangi, because I think she might not be listening here currently, but we'd need her consent for a licence change from GPL (which is generally deemed unsuitable for documentation) to a CC licence.
But it would be entirely possible to manage the book's contents on a different website, using a different system.
Are we moving away from FLOSS because of its license? This is afine point which I don't get. Could someone make this simple for me, too?
- No, the licence discussion is not related to the discussion about finding a suitable editing platform.
The website where the book lives currently, flossmanualsfr.com, is a fine website for writing books. However, it lacks some features that would be very useful for us, e.g. customization, versioning with undo, support for different software versions and languages.
Likewise, the other suggested platforms lack features (especially in contributor-usability), and there exist other platforms that people may know about.
I was hoping to get some input on what is more important to people. To me as someone who would probably be working on the more organizational side, the frontend doesn't matter so much. I'm used to doing my editing in a text editor, and to use a preview. I'm also used to installing/running software on my computer, for testing my edits locally (which wouldn't be mandatory, though - a website that allows to edit the texts is available for each of the items on the list). What matters to me is that it is easy to have multiple versions and translations available, and to be able to automate the process. Also, to allow people who aren't involved in the project yet to do quick edits and request their inclusion into the manual. And to have a highly customizable output - concerning output formats (ebook formats, html, pdf, maybe even an 'app'), and styling of those (which I think CR might enjoy).
But I know that many of the possible editors might be afraid of the gitlab workflow, and I wanted people to be able to take a look at the different options.
I've got one more platform to add to the list (as 'looked at, I'd discourage usage'):
***************
Gitbook
WHAT: node.js-based modern toolchain to build docs from markdown/Asciidoc (locally installable version available) - disclaimer: didn't test, only read.
PROS: - comes with an editor that is graphical, and integrates support for the version control part, so users do not need to worry about learning git or finding their way around the git**b user interfaces. - includes support for multiple language versions - customizable templates / themes - free hosting available
CONS: - the above mentioned editor is proprietary. There exists a no-longer-in-development open source legacy version. - free hosting limited to 5 contributors - all in all (if you take away the limited hosting and the non-free editor) similar to the readthedocs version, but building on a system I wouldn't be able to deal with, userbase / maturity is probably a lot smaller/less than the one of readthedocs/sphinx.
Homepage: https://www.gitbook.com/ Source repo example: https://github.com/GitbookIO/gitbook/tree/master/docs Example web page: https://www.gitbook.com/book/frontendmasters/front-end-handbook/details
****************
Kind Regards, Maren
Thanks, 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-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Am 08.05.2017 um 13:13 schrieb brynn:
Oh, thank you so much for explaining it! Well I'll get subscribed on FLOSS and give the editing a test.
And I'll also read through your notes now, and share comments about the other options, if I have any that are different from yours.
However, it lacks some features that
would be very useful for us, e.g. customization, versioning with undo, support for different software versions and languages.
Versioning? I thought the whole point of a manual which the community can maintain, would be to have A manual, which is theoretically always being edited (although more around Inkscape release times) and always up to date. Do you mean that if people wanted to print as an ebook or download PDF, those would have versions?
- I mean that we need to have a way to prepare a manual for the next release, while not showing those changes in the one that is publicly available. So, e.g. the fillet/chamfer lpe doesn't need to be explained in the manual for 0.91. Screenshots will also look different.
But we may want to have the newer version ready on release, so it could be included with the software (long-term goal, not achievable for the next couple of versions at least, I think).
Also, as we both know, people may use different versions, and will not want to read the wrong instructions.
Languages? It seems like FLOSS does provide support for, well, at least 2 different languages, case in point, the French version which is being translated. Do you mean some kind of automatic translation?
- No, I mean that I would like to have multiple languages in one place, not in two completely separate places, as it is with Booktype. This is so they could share screenshots, and images. Chapters that are not translated will have a fallback in English.
So partial translations would also make sense, and the untranslated parts would always be kept in sync with the English ones (because they *are* the English ones, which are shown when a translation of that file is missing).
Take a look at the django documentation to see how it's organized. You can select different language and program versions there in the overlayed numbers at the bottom right: https://docs.djangoproject.com/en/1.10/topics/i18n/translation/
Maren
Thanks again, brynn
-----Original Message----- From: Maren Hachmann Sent: Sunday, May 07, 2017 2:54 PM To: brynn ; C R ; Inkscape Devel List ; Inkscape-Docs Subject: Re: [Inkscape-devel] Any chance we can make some docs material? (targeting the moon)
Am 05.05.2017 um 16:04 schrieb brynn:
Hi Maren and all, I appreciate your research into, and review of.....well I don't even understand what this is.
Could someone give me a simple explanation? I'm still thinking"translate French FLOSS manual" and then update and expand the translation as a FLOSS doc. I don't think we should abandon that, after all the work that Sylvain and Hineringi have put in. Not to forget the French team too.
- Yes, that would be one of the options (the last one in the list I
posted). But there are more ways to write documentation, especially if you're dealing with maintaining different versions of the software (and thus the manual) in parallel, and different languages.
I'm not suggesting abandoning that book. On the contrary, yesterday I've translated one more short chapter (and found the editor to be less comfortable than the one we have on our django website, esp. for inserting files/pictures), and I've just sent out a private email to Hinerangi, because I think she might not be listening here currently, but we'd need her consent for a licence change from GPL (which is generally deemed unsuitable for documentation) to a CC licence.
But it would be entirely possible to manage the book's contents on a different website, using a different system.
Are we moving away from FLOSS because of its license? This is afine point which I don't get. Could someone make this simple for me, too?
- No, the licence discussion is not related to the discussion about
finding a suitable editing platform.
The website where the book lives currently, flossmanualsfr.com, is a fine website for writing books. However, it lacks some features that would be very useful for us, e.g. customization, versioning with undo, support for different software versions and languages.
Likewise, the other suggested platforms lack features (especially in contributor-usability), and there exist other platforms that people may know about.
I was hoping to get some input on what is more important to people. To me as someone who would probably be working on the more organizational side, the frontend doesn't matter so much. I'm used to doing my editing in a text editor, and to use a preview. I'm also used to installing/running software on my computer, for testing my edits locally (which wouldn't be mandatory, though - a website that allows to edit the texts is available for each of the items on the list). What matters to me is that it is easy to have multiple versions and translations available, and to be able to automate the process. Also, to allow people who aren't involved in the project yet to do quick edits and request their inclusion into the manual. And to have a highly customizable output - concerning output formats (ebook formats, html, pdf, maybe even an 'app'), and styling of those (which I think CR might enjoy).
But I know that many of the possible editors might be afraid of the gitlab workflow, and I wanted people to be able to take a look at the different options.
I've got one more platform to add to the list (as 'looked at, I'd discourage usage'):
Gitbook
WHAT: node.js-based modern toolchain to build docs from markdown/Asciidoc (locally installable version available) - disclaimer: didn't test, only read.
PROS:
- comes with an editor that is graphical, and integrates support for
the version control part, so users do not need to worry about learning git or finding their way around the git**b user interfaces.
- includes support for multiple language versions
- customizable templates / themes
- free hosting available
CONS:
- the above mentioned editor is proprietary. There exists a
no-longer-in-development open source legacy version.
- free hosting limited to 5 contributors
- all in all (if you take away the limited hosting and the non-free
editor) similar to the readthedocs version, but building on a system I wouldn't be able to deal with, userbase / maturity is probably a lot smaller/less than the one of readthedocs/sphinx.
Homepage: https://www.gitbook.com/ Source repo example: https://github.com/GitbookIO/gitbook/tree/master/docs Example web page: https://www.gitbook.com/book/frontendmasters/front-end-handbook/details
Kind Regards, Maren
Thanks, 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-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
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-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
@jazznico: Is there a way to transfer books between the French flossmanuals site and the English one? I.e. would it be possible to export and import a book? Or would it be possible to have a language selection menu on flossmanualsfr instead, with English available for selection? This would make it easier for our international editors to deal with the interface.
Hi Brynn,
thanks for taking a closer look! (I'm so glad someone was able to take the time for this.)
FLOSS is the abbreviation for 'Free/Libre Open Source Software'. The websites are flossmanualsfr.net / flossmanuals.net respectively. They allow for collaborative writing of manuals for FLOSS.
I fully understand the need for a WYSIWYG editor. The one from Booktype is quite okay. Where it lacks is when you want to insert a file or image - because you need to upload it first, then you need to find out that the link to it that you need to enter in the insertion dialog is '/static/filename.ext'. That's more difficult than it would need to be (but you can use the same image file on different pages this way).
(Btw. what do you think of helping with the translation by making sure that all images get uploaded? When I copy-paste from the French book, I get all the images, but they are just links to the original book, not part of the one I'm editing. And it takes quite some time to rename the files to something English, upload, add a useful placeholder text and then exchange the links. I'd prefer to spend that time on translating.)
About the 'location', I've had this silly idea:
As a first step, we create/translate/update this introductory manual at flossmanuals (if possible at the English site, to make it easier for contributors). It's a great way for getting people started with Inkscape.
As a second step, or in parallel, we could also have a more glossary-like, more technical manual, that explains what each menu item /LPE/... does. This technical manual could also be used by developers to document their changes, and it could use the more technical style with Sphinx/reST/readthedocs. It could even start out simple, with keywords / lists, and be refined by people who don't like those ;-)
(btw. I have volunteered to set this up, seems you overlooked ;-) - for customization, translation and version branches, I'd still have to learn a bit, but it doesn't appear to be too hard).
The one issue I see with this split is that it would spread resources (us) a bit wide, maybe. But from the time when I started using Inkscape, I know that having a manual like the one Elisa wrote would have helped me a lot - I barely understood a word in Tav's manual.
Now, as an advanced user, I (claim I) know everything that Elisa explains, but Tav's more technical manual contains so much more info, which I'm now able to understand (and often have the urge to update).
So that's why I think that having two different manuals wouldn't be such a bad idea. The technical manual could be written by the more technical users and, hopefully, devs (when they change something).
Well, just an idea. Let me know if you think it's crap ;-)
Kind Regards, Maren
Am 10.05.2017 um 07:47 schrieb brynn:
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, asopposed 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 forBooktype.
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-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Hello,
Mick Is the manager of floss manuals english. I ask him for the possibility of import the book. I give him the url, he is trying.
Regards, Elisa
2017-05-11 1:07 GMT+02:00 Maren Hachmann <maren@...68...>:
@jazznico: Is there a way to transfer books between the French flossmanuals site and the English one? I.e. would it be possible to export and import a book? Or would it be possible to have a language selection menu on flossmanualsfr instead, with English available for selection? This would make it easier for our international editors to deal with the interface.
Hi Brynn,
thanks for taking a closer look! (I'm so glad someone was able to take the time for this.)
FLOSS is the abbreviation for 'Free/Libre Open Source Software'. The websites are flossmanualsfr.net / flossmanuals.net respectively. They allow for collaborative writing of manuals for FLOSS.
I fully understand the need for a WYSIWYG editor. The one from Booktype is quite okay. Where it lacks is when you want to insert a file or image
- because you need to upload it first, then you need to find out that
the link to it that you need to enter in the insertion dialog is '/static/filename.ext'. That's more difficult than it would need to be (but you can use the same image file on different pages this way).
(Btw. what do you think of helping with the translation by making sure that all images get uploaded? When I copy-paste from the French book, I get all the images, but they are just links to the original book, not part of the one I'm editing. And it takes quite some time to rename the files to something English, upload, add a useful placeholder text and then exchange the links. I'd prefer to spend that time on translating.)
About the 'location', I've had this silly idea:
As a first step, we create/translate/update this introductory manual at flossmanuals (if possible at the English site, to make it easier for contributors). It's a great way for getting people started with Inkscape.
As a second step, or in parallel, we could also have a more glossary-like, more technical manual, that explains what each menu item /LPE/... does. This technical manual could also be used by developers to document their changes, and it could use the more technical style with Sphinx/reST/readthedocs. It could even start out simple, with keywords / lists, and be refined by people who don't like those ;-)
(btw. I have volunteered to set this up, seems you overlooked ;-) - for customization, translation and version branches, I'd still have to learn a bit, but it doesn't appear to be too hard).
The one issue I see with this split is that it would spread resources (us) a bit wide, maybe. But from the time when I started using Inkscape, I know that having a manual like the one Elisa wrote would have helped me a lot - I barely understood a word in Tav's manual.
Now, as an advanced user, I (claim I) know everything that Elisa explains, but Tav's more technical manual contains so much more info, which I'm now able to understand (and often have the urge to update).
So that's why I think that having two different manuals wouldn't be such a bad idea. The technical manual could be written by the more technical users and, hopefully, devs (when they change something).
Well, just an idea. Let me know if you think it's crap ;-)
Kind Regards, Maren
Am 10.05.2017 um 07:47 schrieb brynn:
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, asopposed 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 forBooktype.
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-devel@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
Hi Elisa,
thank you very much for asking the flossmanuals.net manager! Would you keep us updated on whether it works or not?
Kind Regards, Maren
Am 11.05.2017 um 16:09 schrieb Elisa Godoy de Castro Guerra:
Hello,
Mick Is the manager of floss manuals english. I ask him for the possibility of import the book. I give him the url, he is trying.
Regards, Elisa
2017-05-11 1:07 GMT+02:00 Maren Hachmann <maren@...68... mailto:maren@...68...>:
@jazznico: Is there a way to transfer books between the French flossmanuals site and the English one? I.e. would it be possible to export and import a book? Or would it be possible to have a language selection menu on flossmanualsfr instead, with English available for selection? This would make it easier for our international editors to deal with the interface. Hi Brynn, thanks for taking a closer look! (I'm so glad someone was able to take the time for this.) FLOSS is the abbreviation for 'Free/Libre Open Source Software'. The websites are flossmanualsfr.net <http://flossmanualsfr.net> / flossmanuals.net <http://flossmanuals.net> respectively. They allow for collaborative writing of manuals for FLOSS. I fully understand the need for a WYSIWYG editor. The one from Booktype is quite okay. Where it lacks is when you want to insert a file or image - because you need to upload it first, then you need to find out that the link to it that you need to enter in the insertion dialog is '/static/filename.ext'. That's more difficult than it would need to be (but you can use the same image file on different pages this way). (Btw. what do you think of helping with the translation by making sure that all images get uploaded? When I copy-paste from the French book, I get all the images, but they are just links to the original book, not part of the one I'm editing. And it takes quite some time to rename the files to something English, upload, add a useful placeholder text and then exchange the links. I'd prefer to spend that time on translating.) About the 'location', I've had this silly idea: As a first step, we create/translate/update this introductory manual at flossmanuals (if possible at the English site, to make it easier for contributors). It's a great way for getting people started with Inkscape. As a second step, or in parallel, we could also have a more glossary-like, more technical manual, that explains what each menu item /LPE/... does. This technical manual could also be used by developers to document their changes, and it could use the more technical style with Sphinx/reST/readthedocs. It could even start out simple, with keywords / lists, and be refined by people who don't like those ;-) (btw. I have volunteered to set this up, seems you overlooked ;-) - for customization, translation and version branches, I'd still have to learn a bit, but it doesn't appear to be too hard). The one issue I see with this split is that it would spread resources (us) a bit wide, maybe. But from the time when I started using Inkscape, I know that having a manual like the one Elisa wrote would have helped me a lot - I barely understood a word in Tav's manual. Now, as an advanced user, I (claim I) know everything that Elisa explains, but Tav's more technical manual contains so much more info, which I'm now able to understand (and often have the urge to update). So that's why I think that having two different manuals wouldn't be such a bad idea. The technical manual could be written by the more technical users and, hopefully, devs (when they change something). Well, just an idea. Let me know if you think it's crap ;-) Kind Regards, Maren Am 10.05.2017 um 07:47 schrieb brynn: > 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 <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 <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 <http://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 <http://readthedocs.org>, e.g. docs.inkscape.org <http://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 <http://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 <https://gitlab.com/Moini/inkscape-extensions-multi-bool/tree/master/docs> > - rendered documentation: > http://inkscape-multi-bool-extension.readthedocs.io/en/latest/index.html <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/ <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-devel@lists.sourceforge.net <mailto:Inkscape-devel@lists.sourceforge.net> > https://lists.sourceforge.net/lists/listinfo/inkscape-devel <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 <mailto:Inkscape-docs@lists.sourceforge.net> https://lists.sourceforge.net/lists/listinfo/inkscape-docs <https://lists.sourceforge.net/lists/listinfo/inkscape-docs>--
Elisa de Castro Guerra
(Btw. what do you think of helping with the translation by making sure
that all images get uploaded? When I copy-paste from the French book, I get all the images, but they are just links to the original book, not part of the one I'm editing. And it takes quite some time to rename the files to something English, upload, add a useful placeholder text and then exchange the links. I'd prefer to spend that time on translating.)
Sure, if I'm just taking the images from one and putting into the other, I could do that. I just didn't like the idea of making new screenshots, using my theme. Although, at least the images I've looked at so far, already have English names.
Hhmm.... Hopefully Sylvain can answer the questions I asked about the work that has been done to date. (in a different message) (https://sourceforge.net/p/inkscape/mailman/message/35828296/) Could I be looking at the wrong documents? Besides different chapters, I'm seeing vastly different content between the French and the translated English. It's not just translated, it appears to be entirely rewritten, and also using completely different images!
I might think I was mistakenly looking at the original Inkscape Floss Manual, except both of the ones I'm looking are on the fr subdomain. Let's get this straightened out, so I'm working on the right documents. So using "L'outil Sélecteur", which is Selection Tool, right? To me, this page:
https://fr.flossmanuals.net/start-with-inkscape/select-tool/
is not just a translation of
https://fr.flossmanuals.net/inkscape/selector-tool-a/
I certainly don't mind editing the pages that are already translated, to put the same images from the French manual, but I'd have to make major text edits too. (Or we, or whomever.)
Surely one of the 2 I'm looking at is the wrong one?
Re: "silly idea" Some comments.
-- Not so silly. -- Since we already do have the technical style of manual, outdated though it may be, I would suggest getting the new one finished and published first. -- Perhaps Tav would consider releasing the content of his current manual, to be used as a starting point for the technical one? -- Likely certain people would be better suited for writing this more technical one. I know for myself, I couldn't write it, no matter how hard I tried. Often I find myself writing in simple language, even when I know the reader doesn't need it simplified. Must be in my DNA, haha. -- I wonder if having 2 manuals would be confusing for users? I think as long as the titles of the manuals makes it very clear, it would be ok. Such as Introduction to Inkscape for the beginnners' manual or Technical Inkscape Manual for the other. Something like that. (And also make sure the URLs include the distinction, so searching isn't confusing either.)
(btw. I have volunteered to set this up, seems you overlooked ;-) - for
customization, translation and version branches, I'd still have to learn a bit, but it doesn't appear to be too hard).
No, I read it. But since I was "voting" for the Booktype option, I didn't have any reason to make a comment about setting up the Sphinx option.
I sincerely hope I have a wrong manual that I'm looking at, and that we don't have a serious problem with the translation being not strictly a translation!
Somewhat random thought. I guess both Floss Manuals and Booktypes can be themed or branded? Perhaps at some time during this manual-translating and then writing process, the community can have a discussion about Inkscape branding? I'm not sure if we can say it's overdue, but I would suggest that the time has come :-)
All best, brynn
-----Original Message----- From: Maren Hachmann Sent: Wednesday, May 10, 2017 5:07 PM To: brynn ; C R ; Inkscape Devel List ; Inkscape-Docs Subject: Re: [Inkscape-devel] Any chance we can make some docs material? (targeting the moon)
@jazznico: Is there a way to transfer books between the French flossmanuals site and the English one? I.e. would it be possible to export and import a book? Or would it be possible to have a language selection menu on flossmanualsfr instead, with English available for selection? This would make it easier for our international editors to deal with the interface.
Hi Brynn,
thanks for taking a closer look! (I'm so glad someone was able to take the time for this.)
FLOSS is the abbreviation for 'Free/Libre Open Source Software'. The websites are flossmanualsfr.net / flossmanuals.net respectively. They allow for collaborative writing of manuals for FLOSS.
I fully understand the need for a WYSIWYG editor. The one from Booktype is quite okay. Where it lacks is when you want to insert a file or image - because you need to upload it first, then you need to find out that the link to it that you need to enter in the insertion dialog is '/static/filename.ext'. That's more difficult than it would need to be (but you can use the same image file on different pages this way).
(Btw. what do you think of helping with the translation by making sure that all images get uploaded? When I copy-paste from the French book, I get all the images, but they are just links to the original book, not part of the one I'm editing. And it takes quite some time to rename the files to something English, upload, add a useful placeholder text and then exchange the links. I'd prefer to spend that time on translating.)
About the 'location', I've had this silly idea:
As a first step, we create/translate/update this introductory manual at flossmanuals (if possible at the English site, to make it easier for contributors). It's a great way for getting people started with Inkscape.
As a second step, or in parallel, we could also have a more glossary-like, more technical manual, that explains what each menu item /LPE/... does. This technical manual could also be used by developers to document their changes, and it could use the more technical style with Sphinx/reST/readthedocs. It could even start out simple, with keywords / lists, and be refined by people who don't like those ;-)
(btw. I have volunteered to set this up, seems you overlooked ;-) - for customization, translation and version branches, I'd still have to learn a bit, but it doesn't appear to be too hard).
The one issue I see with this split is that it would spread resources (us) a bit wide, maybe. But from the time when I started using Inkscape, I know that having a manual like the one Elisa wrote would have helped me a lot - I barely understood a word in Tav's manual.
Now, as an advanced user, I (claim I) know everything that Elisa explains, but Tav's more technical manual contains so much more info, which I'm now able to understand (and often have the urge to update).
So that's why I think that having two different manuals wouldn't be such a bad idea. The technical manual could be written by the more technical users and, hopefully, devs (when they change something).
Well, just an idea. Let me know if you think it's crap ;-)
Kind Regards, Maren
Am 10.05.2017 um 07:47 schrieb brynn:
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, asopposed 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 forBooktype.
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-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
Hi Brynn,
indeed, you got the wrong book, Brynn. Just wait a day or two (or however long it'll take to contact Mick and get a couple of things sorted out), then you'll see. We're definitely going to need someone who renames the images that will be in that book. You don't need to work on it yet.
-- Not so silly.
- Oh :)
-- Since we already do have the technical style of manual, outdated though it may be, I would suggest getting the new one finished and published first.
- I agree.
-- Perhaps Tav would consider releasing the content of his current manual, to be used as a starting point for the technical one?
- I already had asked him about this, and, AFAIR, his answer went into the direction of 'This may be difficult to do (because the book is copyrighted and a publisher holds the rights), don't count on it ever happening. Rather start something new.'
-- Likely certain people would be better suited for writing this more technical one. I know for myself, I couldn't write it, no matter how hard I tried. Often I find myself writing in simple language, even when I know the reader doesn't need it simplified. Must be in my DNA, haha.
- There may be others reading it, aside from the person who asked.
-- I wonder if having 2 manuals would be confusing for users? I think as long as the titles of the manuals makes it very clear, it would be ok. Such as Introduction to Inkscape for the beginnners' manual or Technical Inkscape Manual for the other. Something like that. (And also make sure the URLs include the distinction, so searching isn't confusing either.)
- Yes, I agree 100%.
Somewhat random thought. I guess both Floss Manuals and Booktypes can be themed or branded? Perhaps at some time during this manual-translating and then writing process, the community can have a discussion about Inkscape branding? I'm not sure if we can say it's overdue, but I would suggest that the time has come :-)
- flossmanuals does appear to have an option for adding some kind of home page. It seems to be a bit complicated, but possible. Not so much for branding the book, there are three themes to choose from, which is an experimental option (and I haven't tested). But as it's html, it may be possible to do some post-processing...
(*This* kind of thing is a lot more controllable with readthedocs/Sphinx.)
It's not very high priority, though. However, it would be extremely cool if we could manage to have a pdf or a set of web pages ready for inclusion in one of the next Inkscape versions this year.
Maren
Am 12.05.2017 um 08:00 schrieb brynn:
(Btw. what do you think of helping with the translation by making sure
that all images get uploaded? When I copy-paste from the French book, I get all the images, but they are just links to the original book, not part of the one I'm editing. And it takes quite some time to rename the files to something English, upload, add a useful placeholder text and then exchange the links. I'd prefer to spend that time on translating.)
Sure, if I'm just taking the images from one and putting into the other, I could do that. I just didn't like the idea of making new screenshots, using my theme. Although, at least the images I've looked at so far, already have English names.
Hhmm.... Hopefully Sylvain can answer the questions I asked about the work that has been done to date. (in a different message) (https://sourceforge.net/p/inkscape/mailman/message/35828296/) Could I be looking at the wrong documents? Besides different chapters, I'm seeing vastly different content between the French and the translated English. It's not just translated, it appears to be entirely rewritten, and also using completely different images!
I might think I was mistakenly looking at the original Inkscape Floss Manual, except both of the ones I'm looking are on the fr subdomain. Let's get this straightened out, so I'm working on the right documents. So using "L'outil Sélecteur", which is Selection Tool, right? To me, this page:
https://fr.flossmanuals.net/start-with-inkscape/select-tool/
is not just a translation of
https://fr.flossmanuals.net/inkscape/selector-tool-a/
I certainly don't mind editing the pages that are already translated, to put the same images from the French manual, but I'd have to make major text edits too. (Or we, or whomever.)
Surely one of the 2 I'm looking at is the wrong one?
Re: "silly idea" Some comments.
-- Not so silly. -- Since we already do have the technical style of manual, outdated though it may be, I would suggest getting the new one finished and published first. -- Perhaps Tav would consider releasing the content of his current manual, to be used as a starting point for the technical one? -- Likely certain people would be better suited for writing this more technical one. I know for myself, I couldn't write it, no matter how hard I tried. Often I find myself writing in simple language, even when I know the reader doesn't need it simplified. Must be in my DNA, haha. -- I wonder if having 2 manuals would be confusing for users? I think as long as the titles of the manuals makes it very clear, it would be ok. Such as Introduction to Inkscape for the beginnners' manual or Technical Inkscape Manual for the other. Something like that. (And also make sure the URLs include the distinction, so searching isn't confusing either.)
(btw. I have volunteered to set this up, seems you overlooked ;-) - for
customization, translation and version branches, I'd still have to learn a bit, but it doesn't appear to be too hard).
No, I read it. But since I was "voting" for the Booktype option, I didn't have any reason to make a comment about setting up the Sphinx option.
I sincerely hope I have a wrong manual that I'm looking at, and that we don't have a serious problem with the translation being not strictly a translation!
Somewhat random thought. I guess both Floss Manuals and Booktypes can be themed or branded? Perhaps at some time during this manual-translating and then writing process, the community can have a discussion about Inkscape branding? I'm not sure if we can say it's overdue, but I would suggest that the time has come :-)
All best, brynn
-----Original Message----- From: Maren Hachmann Sent: Wednesday, May 10, 2017 5:07 PM To: brynn ; C R ; Inkscape Devel List ; Inkscape-Docs Subject: Re: [Inkscape-devel] Any chance we can make some docs material? (targeting the moon)
@jazznico: Is there a way to transfer books between the French flossmanuals site and the English one? I.e. would it be possible to export and import a book? Or would it be possible to have a language selection menu on flossmanualsfr instead, with English available for selection? This would make it easier for our international editors to deal with the interface.
Hi Brynn,
thanks for taking a closer look! (I'm so glad someone was able to take the time for this.)
FLOSS is the abbreviation for 'Free/Libre Open Source Software'. The websites are flossmanualsfr.net / flossmanuals.net respectively. They allow for collaborative writing of manuals for FLOSS.
I fully understand the need for a WYSIWYG editor. The one from Booktype is quite okay. Where it lacks is when you want to insert a file or image
- because you need to upload it first, then you need to find out that
the link to it that you need to enter in the insertion dialog is '/static/filename.ext'. That's more difficult than it would need to be (but you can use the same image file on different pages this way).
(Btw. what do you think of helping with the translation by making sure that all images get uploaded? When I copy-paste from the French book, I get all the images, but they are just links to the original book, not part of the one I'm editing. And it takes quite some time to rename the files to something English, upload, add a useful placeholder text and then exchange the links. I'd prefer to spend that time on translating.)
About the 'location', I've had this silly idea:
As a first step, we create/translate/update this introductory manual at flossmanuals (if possible at the English site, to make it easier for contributors). It's a great way for getting people started with Inkscape.
As a second step, or in parallel, we could also have a more glossary-like, more technical manual, that explains what each menu item /LPE/... does. This technical manual could also be used by developers to document their changes, and it could use the more technical style with Sphinx/reST/readthedocs. It could even start out simple, with keywords / lists, and be refined by people who don't like those ;-)
(btw. I have volunteered to set this up, seems you overlooked ;-) - for customization, translation and version branches, I'd still have to learn a bit, but it doesn't appear to be too hard).
The one issue I see with this split is that it would spread resources (us) a bit wide, maybe. But from the time when I started using Inkscape, I know that having a manual like the one Elisa wrote would have helped me a lot - I barely understood a word in Tav's manual.
Now, as an advanced user, I (claim I) know everything that Elisa explains, but Tav's more technical manual contains so much more info, which I'm now able to understand (and often have the urge to update).
So that's why I think that having two different manuals wouldn't be such a bad idea. The technical manual could be written by the more technical users and, hopefully, devs (when they change something).
Well, just an idea. Let me know if you think it's crap ;-)
Kind Regards, Maren
Am 10.05.2017 um 07:47 schrieb brynn:
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, asopposed 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 forBooktype.
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-devel@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-devel
2017-05-11 22:55 GMT+02:00 Maren Hachmann <maren@...68...>:
Hi Elisa,
thank you very much for asking the flossmanuals.net manager! Would you keep us updated on whether it works or not?
yes of course.
Elisa
Kind Regards, Maren
Am 11.05.2017 um 16:09 schrieb Elisa Godoy de Castro Guerra:
Hello,
Mick Is the manager of floss manuals english. I ask him for the possibility of import the book. I give him the url, he is trying.
Regards, Elisa
2017-05-11 1:07 GMT+02:00 Maren Hachmann <maren@...68... mailto:maren@...68...>:
@jazznico: Is there a way to transfer books between the French flossmanuals site and the English one? I.e. would it be possible to export and import a book? Or would it be possible to have a language selection menu on flossmanualsfr instead, with English available for selection? This would make it easier for our international editors to deal with the interface. Hi Brynn, thanks for taking a closer look! (I'm so glad someone was able totake
the time for this.) FLOSS is the abbreviation for 'Free/Libre Open Source Software'. The websites are flossmanualsfr.net <http://flossmanualsfr.net> / flossmanuals.net <http://flossmanuals.net> respectively. They allow for collaborative writing of manuals for FLOSS. I fully understand the need for a WYSIWYG editor. The one fromBooktype
is quite okay. Where it lacks is when you want to insert a file orimage
- because you need to upload it first, then you need to find out that the link to it that you need to enter in the insertion dialog is '/static/filename.ext'. That's more difficult than it would need tobe
(but you can use the same image file on different pages this way). (Btw. what do you think of helping with the translation by makingsure
that all images get uploaded? When I copy-paste from the Frenchbook, I
get all the images, but they are just links to the original book, not part of the one I'm editing. And it takes quite some time to renamethe
files to something English, upload, add a useful placeholder textand
then exchange the links. I'd prefer to spend that time ontranslating.)
About the 'location', I've had this silly idea: As a first step, we create/translate/update this introductory manualat
flossmanuals (if possible at the English site, to make it easier for contributors). It's a great way for getting people started with Inkscape. As a second step, or in parallel, we could also have a more glossary-like, more technical manual, that explains what each menuitem
/LPE/... does. This technical manual could also be used bydevelopers to
document their changes, and it could use the more technical stylewith
Sphinx/reST/readthedocs. It could even start out simple, withkeywords /
lists, and be refined by people who don't like those ;-) (btw. I have volunteered to set this up, seems you overlooked ;-) -for
customization, translation and version branches, I'd still have tolearn
a bit, but it doesn't appear to be too hard). The one issue I see with this split is that it would spread resources (us) a bit wide, maybe. But from the time when I started usingInkscape,
I know that having a manual like the one Elisa wrote would havehelped
me a lot - I barely understood a word in Tav's manual. Now, as an advanced user, I (claim I) know everything that Elisa explains, but Tav's more technical manual contains so much more info, which I'm now able to understand (and often have the urge to update). So that's why I think that having two different manuals wouldn't besuch
a bad idea. The technical manual could be written by the moretechnical
users and, hopefully, devs (when they change something). Well, just an idea. Let me know if you think it's crap ;-) Kind Regards, Maren Am 10.05.2017 um 07:47 schrieb brynn: > Hi Everyone, > I've tried to read up and study and understand the infowhich
> Maren presented. Because my understanding is extremely limited, I > hesitate to offer any comments at all. But for whatever it mightbe
> 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 Consare
> 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 exportedout or
> transfered elsewhere for publishing, right? > > Gitlab Wiki + X > It seems to me like the lack of a wysiwyg editor is the mostlimiting
> factor (at least for as much as I understand). I'm just thinking of > people who might be interested in joining the manual ordocumentation
> 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 adminfor
> 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 thatmight
> 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 votefor
> 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 feelI
> 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 <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 startwriting
> for trunk, and continue fixing for stable) > - no direct translation support > - support for the backend depends upon a single individual, nouser
> 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), orlooking
> at a diff > > EXAMPLE (frontend): https://gitlab.com/inkscape/inkscape-web/wikis/home <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 <http://readthedocs.org> on save (i.e. commit). > > PROS: > - available quickly (didn't know how it works exactly, but gotit
> 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 docsare
> 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 <http://readthedocs.org>, e.g. docs.inkscape.org <http://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 <http://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 usageinstructions, 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
<https://gitlab.com/Moini/inkscape-extensions-multi-bool/tree/master/docs>
> - rendered documentation: > http://inkscape-multi-bool-extension.readthedocs.io/en/latest/index.html
<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 andeasy to
> solve.) > > EXAMPLE (rendered documentation): > https://www.flossmanualsfr.net/initiation-inkscape/ <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 thedocumentation
> 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-devel@lists.sourceforge.net <mailto:Inkscape-devel@lists.sourceforge.net> > https://lists.sourceforge.net/lists/listinfo/inkscape-devel <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 <mailto:Inkscape-docs@lists.sourceforge.net> https://lists.sourceforge.net/lists/listinfo/inkscape-docs <https://lists.sourceforge.net/lists/listinfo/inkscape-docs>--
Elisa de Castro Guerra
Hi everyone,
join us for translating and editing the Inkscape Beginners' manual, which is based upon Elisa de Castro Guerra's French book "Initiation à Inkscape" (Original French version available at https://www.flossmanualsfr.net/initiation-inkscape/ - don't translate this one ;-) ) ! Thank you, Elisa, for sharing your work and helping with licencing (also for joining the admins)!
The plan is to translate the book from French to English (Sylvain and Hinerangi already did some of the work), and make adjustments as we see fit, then to make it available for people who only start using Inkscape - if possible, accessible directly from inside the Inkscape program.
Here are some notes to get you started (we may tweak processes later, if we find better ones):
Platform usage ==============
This book is written at flossmanuals.net, which is a website that allows for collaborative editing of books about Free/Libre and Open Source Software. To learn more about the community that's behind it, please visit http://www.flossmanuals.org/about-floss-manuals-foundation.
The manual for this 'manual writing platform' (which is an instance of the Booktype software), is available at http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/ .
Joining =======
Join the group at http://write.flossmanuals.net/groups/beginners-manual-for-inkscape/ :-) Also say hi on the docs mailing list (see below, section "Communication", so we know who is who, and what you can help with.
Editing =======
IMPORTANT: When you're editing the book, ALWAYS leave a screen either by clicking on the 'Cancel' or on the 'Save' button. This is because, if you leave it by just closing the tab in your browser, the chapter will stay locked and inaccessible for other editors.
Version =======
This book will refer to the Inkscape 0.92.x series (important for your screenshots!).
Writing Style =============
This book is meant as an introduction for people who are not yet familiar with Inkscape terminology.
When deciding how to phrase something, think of yourself when you started to use a vector editor, or think of a teen who you would like to introduce to the program, and who you would like to enjoy the process, and to be able to make nice drawings after reading the book.
Stay on topic, make it easy to understand, and keep the learning curve shallow. Write less rather than more. Be nice and encouraging to the reader. There exists another manual that provides the deep, technical details. We need to keep in mind that it will also be read by people whose native language is not English.
Communication ===============
Anyone who edits the book can exchange messages, files and snippets via chat with other users who are online at the same time. For discussions of wider interest, or when you hit an obstacle, please subscribe and send a message to the inkscape-docs mailing list at https://sourceforge.net/p/inkscape/mailman/inkscape-docs/ .
Currently, we have 4 book admins (Elisa, Brynn, CR and me). Admins can change the book settings, add other admins and create release versions.
Chapter status ==============
Chapters move from one status to the next, when they're being worked on:
1. needs translation: Chapter isn't (fully) translated yet. If you speak both French and English, this is where your help is needed! This step only requires you to work on the text. You can ignore any images.
2. to be proofed: Chapter is translated, and needs to be checked by someone other than the translator, to spot errors and do some polishing. If English is your native language and you're good with words, grab this job!
3. needs images: The chapter contains images, but those are still French. Either it's just their file names that need to be changed (Workflow: download image, rename it on your computer, reupload, change link in the Chapter(s), provide meaningful alt text, delete French image) or a new screenshot is needed from the English interface. If you know how to do these things, please jump right in! (Hint: all image links follow this scheme: static/image_file.ext)
4. completed: This chapter is more or less finished. Concentrate your effort on the other ones :) If you spot a mistake or typo, improvements are still possible, of course.
Important: Don't forget to update a chapter's status, after you have worked on it ;-)
When you've got a great idea that would introduce a major change in the book's structure, please confer with other editors on the mailing list to see what they think about this.
Cover =====
If you're good at creating meaningful art, then we need you for creating a cool cover image that shows what you can do with Inkscape and is inviting for beginners. Read more about the Cover Manager in Booktype at http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/_dra.... Let us know about your plans on the mailing list (see section about Communication).
Styling and Customization ======================
If you know your CSS, you can help by improving the book's styling. You can read all about customization for different output formats and the front page in the design section of the Booktype manual at http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/form....
For the book to appear on the flossmanuals.net frontpage, the steps outlined here are required: http://write.flossmanuals.net/floss-manuals-workflow/_draft/_v/1.0/how-do-i-... , section "Publish new details..."
License =======
This book is licensed under the Creative Commons Attribution 4.0 license (CC-By 4.0, see https://creativecommons.org/licenses/by/4.0/). By contributing to this book, you agree to publish your content under this license.
As a contributor, please add your name to the list in the 'About this Book' chapter. This chapter will *always* be in need of new content ;-)
Go! === Have fun working on the book at http://write.flossmanuals.net/start-with-inkscape/_edit/#
You will find a copy of these notes in the 'Notes' tab, and you will find me working on translating French -> English there, in the late evenings (CEST).
See you there, Kind Regards, Maren
I'm so happy we got to this point! Really happy! Can't believe it we were able to solve this and finally, start editing this new material!!! ;-D
Congrats to everyone involved in clearing the way for this to become true.
Cheers,
--Victor Westmann
2017-05-15 15:24 GMT-07:00 Maren Hachmann <maren@...68...>:
Hi everyone,
join us for translating and editing the Inkscape Beginners' manual, which is based upon Elisa de Castro Guerra's French book "Initiation à Inkscape" (Original French version available at https://www.flossmanualsfr.net/initiation-inkscape/ - don't translate this one ;-) ) ! Thank you, Elisa, for sharing your work and helping with licencing (also for joining the admins)!
The plan is to translate the book from French to English (Sylvain and Hinerangi already did some of the work), and make adjustments as we see fit, then to make it available for people who only start using Inkscape
- if possible, accessible directly from inside the Inkscape program.
Here are some notes to get you started (we may tweak processes later, if we find better ones):
Platform usage
This book is written at flossmanuals.net, which is a website that allows for collaborative editing of books about Free/Libre and Open Source Software. To learn more about the community that's behind it, please visit http://www.flossmanuals.org/about-floss-manuals-foundation.
The manual for this 'manual writing platform' (which is an instance of the Booktype software), is available at http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/ .
Joining
Join the group at http://write.flossmanuals.net/groups/beginners-manual-for-inkscape/ :-) Also say hi on the docs mailing list (see below, section "Communication", so we know who is who, and what you can help with.
Editing
IMPORTANT: When you're editing the book, ALWAYS leave a screen either by clicking on the 'Cancel' or on the 'Save' button. This is because, if you leave it by just closing the tab in your browser, the chapter will stay locked and inaccessible for other editors.
Version
This book will refer to the Inkscape 0.92.x series (important for your screenshots!).
Writing Style
This book is meant as an introduction for people who are not yet familiar with Inkscape terminology.
When deciding how to phrase something, think of yourself when you started to use a vector editor, or think of a teen who you would like to introduce to the program, and who you would like to enjoy the process, and to be able to make nice drawings after reading the book.
Stay on topic, make it easy to understand, and keep the learning curve shallow. Write less rather than more. Be nice and encouraging to the reader. There exists another manual that provides the deep, technical details. We need to keep in mind that it will also be read by people whose native language is not English.
Communication
Anyone who edits the book can exchange messages, files and snippets via chat with other users who are online at the same time. For discussions of wider interest, or when you hit an obstacle, please subscribe and send a message to the inkscape-docs mailing list at https://sourceforge.net/p/inkscape/mailman/inkscape-docs/ .
Currently, we have 4 book admins (Elisa, Brynn, CR and me). Admins can change the book settings, add other admins and create release versions.
Chapter status
Chapters move from one status to the next, when they're being worked on:
- needs translation:
Chapter isn't (fully) translated yet. If you speak both French and English, this is where your help is needed! This step only requires you to work on the text. You can ignore any images.
- to be proofed:
Chapter is translated, and needs to be checked by someone other than the translator, to spot errors and do some polishing. If English is your native language and you're good with words, grab this job!
- needs images:
The chapter contains images, but those are still French. Either it's just their file names that need to be changed (Workflow: download image, rename it on your computer, reupload, change link in the Chapter(s), provide meaningful alt text, delete French image) or a new screenshot is needed from the English interface. If you know how to do these things, please jump right in! (Hint: all image links follow this scheme: static/image_file.ext)
- completed:
This chapter is more or less finished. Concentrate your effort on the other ones :) If you spot a mistake or typo, improvements are still possible, of course.
Important: Don't forget to update a chapter's status, after you have worked on it ;-)
When you've got a great idea that would introduce a major change in the book's structure, please confer with other editors on the mailing list to see what they think about this.
Cover
If you're good at creating meaningful art, then we need you for creating a cool cover image that shows what you can do with Inkscape and is inviting for beginners. Read more about the Cover Manager in Booktype at http://sourcefabric.booktype.pro/booktype-16-for-authors-and -publishers/_draft/_v/1.0/the-edit-interface/. Let us know about your plans on the mailing list (see section about Communication).
Styling and Customization
If you know your CSS, you can help by improving the book's styling. You can read all about customization for different output formats and the front page in the design section of the Booktype manual at http://sourcefabric.booktype.pro/booktype-16-for-authors-and -publishers/formless-content/.
For the book to appear on the flossmanuals.net frontpage, the steps outlined here are required: http://write.flossmanuals.net/floss-manuals-workflow/_draft/ _v/1.0/how-do-i-make-an-updated-version-of-a-manual/ , section "Publish new details..."
License
This book is licensed under the Creative Commons Attribution 4.0 license (CC-By 4.0, see https://creativecommons.org/licenses/by/4.0/). By contributing to this book, you agree to publish your content under this license.
As a contributor, please add your name to the list in the 'About this Book' chapter. This chapter will *always* be in need of new content ;-)
Go!
Have fun working on the book at http://write.flossmanuals.net/start-with-inkscape/_edit/#
You will find a copy of these notes in the 'Notes' tab, and you will find me working on translating French -> English there, in the late evenings (CEST).
See you there, Kind 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-docs mailing list Inkscape-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/inkscape-docs
Hi Victor,
:)
Will you join us there?
Maren
Am 16.05.2017 um 00:48 schrieb Victor Westmann:
I'm so happy we got to this point! Really happy! Can't believe it we were able to solve this and finally, start editing this new material!!! ;-D
Congrats to everyone involved in clearing the way for this to become true.
Cheers,
--Victor Westmann
2017-05-15 15:24 GMT-07:00 Maren Hachmann <maren@...68... mailto:maren@...68...>:
Hi everyone, join us for translating and editing the Inkscape Beginners' manual, which is based upon Elisa de Castro Guerra's French book "Initiation à Inkscape" (Original French version available at https://www.flossmanualsfr.net/initiation-inkscape/ <https://www.flossmanualsfr.net/initiation-inkscape/> - don't translate this one ;-) ) ! Thank you, Elisa, for sharing your work and helping with licencing (also for joining the admins)! The plan is to translate the book from French to English (Sylvain and Hinerangi already did some of the work), and make adjustments as we see fit, then to make it available for people who only start using Inkscape - if possible, accessible directly from inside the Inkscape program. Here are some notes to get you started (we may tweak processes later, if we find better ones): Platform usage ============== This book is written at flossmanuals.net <http://flossmanuals.net>, which is a website that allows for collaborative editing of books about Free/Libre and Open Source Software. To learn more about the community that's behind it, please visit http://www.flossmanuals.org/about-floss-manuals-foundation <http://www.flossmanuals.org/about-floss-manuals-foundation>. The manual for this 'manual writing platform' (which is an instance of the Booktype software), is available at http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/ <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/> . Joining ======= Join the group at http://write.flossmanuals.net/groups/beginners-manual-for-inkscape/ <http://write.flossmanuals.net/groups/beginners-manual-for-inkscape/> :-) Also say hi on the docs mailing list (see below, section "Communication", so we know who is who, and what you can help with. Editing ======= IMPORTANT: When you're editing the book, ALWAYS leave a screen either by clicking on the 'Cancel' or on the 'Save' button. This is because, if you leave it by just closing the tab in your browser, the chapter will stay locked and inaccessible for other editors. Version ======= This book will refer to the Inkscape 0.92.x series (important for your screenshots!). Writing Style ============= This book is meant as an introduction for people who are not yet familiar with Inkscape terminology. When deciding how to phrase something, think of yourself when you started to use a vector editor, or think of a teen who you would like to introduce to the program, and who you would like to enjoy the process, and to be able to make nice drawings after reading the book. Stay on topic, make it easy to understand, and keep the learning curve shallow. Write less rather than more. Be nice and encouraging to the reader. There exists another manual that provides the deep, technical details. We need to keep in mind that it will also be read by people whose native language is not English. Communication =============== Anyone who edits the book can exchange messages, files and snippets via chat with other users who are online at the same time. For discussions of wider interest, or when you hit an obstacle, please subscribe and send a message to the inkscape-docs mailing list at https://sourceforge.net/p/inkscape/mailman/inkscape-docs/ <https://sourceforge.net/p/inkscape/mailman/inkscape-docs/> . Currently, we have 4 book admins (Elisa, Brynn, CR and me). Admins can change the book settings, add other admins and create release versions. Chapter status ============== Chapters move from one status to the next, when they're being worked on: 1. needs translation: Chapter isn't (fully) translated yet. If you speak both French and English, this is where your help is needed! This step only requires you to work on the text. You can ignore any images. 2. to be proofed: Chapter is translated, and needs to be checked by someone other than the translator, to spot errors and do some polishing. If English is your native language and you're good with words, grab this job! 3. needs images: The chapter contains images, but those are still French. Either it's just their file names that need to be changed (Workflow: download image, rename it on your computer, reupload, change link in the Chapter(s), provide meaningful alt text, delete French image) or a new screenshot is needed from the English interface. If you know how to do these things, please jump right in! (Hint: all image links follow this scheme: static/image_file.ext) 4. completed: This chapter is more or less finished. Concentrate your effort on the other ones :) If you spot a mistake or typo, improvements are still possible, of course. Important: Don't forget to update a chapter's status, after you have worked on it ;-) When you've got a great idea that would introduce a major change in the book's structure, please confer with other editors on the mailing list to see what they think about this. Cover ===== If you're good at creating meaningful art, then we need you for creating a cool cover image that shows what you can do with Inkscape and is inviting for beginners. Read more about the Cover Manager in Booktype at http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/_draft/_v/1.0/the-edit-interface/ <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/_draft/_v/1.0/the-edit-interface/>. Let us know about your plans on the mailing list (see section about Communication). Styling and Customization ====================== If you know your CSS, you can help by improving the book's styling. You can read all about customization for different output formats and the front page in the design section of the Booktype manual at http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/formless-content/ <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/formless-content/>. For the book to appear on the flossmanuals.net <http://flossmanuals.net> frontpage, the steps outlined here are required: http://write.flossmanuals.net/floss-manuals-workflow/_draft/_v/1.0/how-do-i-make-an-updated-version-of-a-manual/ <http://write.flossmanuals.net/floss-manuals-workflow/_draft/_v/1.0/how-do-i-make-an-updated-version-of-a-manual/> , section "Publish new details..." License ======= This book is licensed under the Creative Commons Attribution 4.0 license (CC-By 4.0, see https://creativecommons.org/licenses/by/4.0/ <https://creativecommons.org/licenses/by/4.0/>). By contributing to this book, you agree to publish your content under this license. As a contributor, please add your name to the list in the 'About this Book' chapter. This chapter will *always* be in need of new content ;-) Go! === Have fun working on the book at http://write.flossmanuals.net/start-with-inkscape/_edit/# <http://write.flossmanuals.net/start-with-inkscape/_edit/#> You will find a copy of these notes in the 'Notes' tab, and you will find me working on translating French -> English there, in the late evenings (CEST). See you there, Kind 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-docs mailing list Inkscape-docs@lists.sourceforge.net <mailto:Inkscape-docs@lists.sourceforge.net> https://lists.sourceforge.net/lists/listinfo/inkscape-docs <https://lists.sourceforge.net/lists/listinfo/inkscape-docs>
Hi Maren,
I just did.
Cheers,
--Victor Westmann
2017-05-16 13:16 GMT-07:00 Maren Hachmann <maren@...68...>:
Hi Victor,
:)
Will you join us there?
Maren
Am 16.05.2017 um 00:48 schrieb Victor Westmann:
I'm so happy we got to this point! Really happy! Can't believe it we were able to solve this and finally, start editing this new material!!!
;-D
Congrats to everyone involved in clearing the way for this to become
true.
Cheers,
--Victor Westmann
2017-05-15 15:24 GMT-07:00 Maren Hachmann <maren@...68... mailto:maren@...68...>:
Hi everyone, join us for translating and editing the Inkscape Beginners' manual, which is based upon Elisa de Castro Guerra's French book "Initiationà
Inkscape" (Original French version available at https://www.flossmanualsfr.net/initiation-inkscape/ <https://www.flossmanualsfr.net/initiation-inkscape/> - don'ttranslate
this one ;-) ) ! Thank you, Elisa, for sharing your work and helping with licencing(also
for joining the admins)! The plan is to translate the book from French to English (Sylvain and Hinerangi already did some of the work), and make adjustments as wesee
fit, then to make it available for people who only start usingInkscape
- if possible, accessible directly from inside the Inkscape program. Here are some notes to get you started (we may tweak processeslater, if
we find better ones): Platform usage ============== This book is written at flossmanuals.net <http://flossmanuals.net>, which is a website that allows for collaborative editing of books about Free/Libre and Open Source Software. To learn more about the community that's behind it, please visit http://www.flossmanuals.org/about-floss-manuals-foundation <http://www.flossmanuals.org/about-floss-manuals-foundation>. The manual for this 'manual writing platform' (which is an instanceof
the Booktype software), is available at http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/
<http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/>
. Joining ======= Join the group at http://write.flossmanuals.net/groups/beginners-manual-for-inkscape/ <http://write.flossmanuals.net/groups/beginners-manual-for-inkscape/>:-)
Also say hi on the docs mailing list (see below, section "Communication", so we know who is who, and what you can help with. Editing ======= IMPORTANT: When you're editing the book, ALWAYS leave a screeneither by
clicking on the 'Cancel' or on the 'Save' button. This is because, if you leave it by just closing the tab in your browser, the chapterwill
stay locked and inaccessible for other editors. Version ======= This book will refer to the Inkscape 0.92.x series (important foryour
screenshots!). Writing Style ============= This book is meant as an introduction for people who are not yet familiar with Inkscape terminology. When deciding how to phrase something, think of yourself when you started to use a vector editor, or think of a teen who you wouldlike to
introduce to the program, and who you would like to enjoy theprocess,
and to be able to make nice drawings after reading the book. Stay on topic, make it easy to understand, and keep the learningcurve
shallow. Write less rather than more. Be nice and encouraging to the reader. There exists another manual that provides the deep, technical details. We need to keep in mind that it will also be read by people whose native language is not English. Communication =============== Anyone who edits the book can exchange messages, files and snippetsvia
chat with other users who are online at the same time. For discussions of wider interest, or when you hit an obstacle,please
subscribe and send a message to the inkscape-docs mailing list at https://sourceforge.net/p/inkscape/mailman/inkscape-docs/ <https://sourceforge.net/p/inkscape/mailman/inkscape-docs/> . Currently, we have 4 book admins (Elisa, Brynn, CR and me). Adminscan
change the book settings, add other admins and create releaseversions.
Chapter status ============== Chapters move from one status to the next, when they're being workedon:
1. needs translation: Chapter isn't (fully) translated yet. If you speak both French and English, this is where your help is needed! This step only requiresyou
to work on the text. You can ignore any images. 2. to be proofed: Chapter is translated, and needs to be checked by someone other thanthe
translator, to spot errors and do some polishing. If English is your native language and you're good with words, grab this job! 3. needs images: The chapter contains images, but those are still French. Either it's just their file names that need to be changed (Workflow: downloadimage,
rename it on your computer, reupload, change link in the Chapter(s), provide meaningful alt text, delete French image) or a newscreenshot is
needed from the English interface. If you know how to do thesethings,
please jump right in! (Hint: all image links follow this scheme: static/image_file.ext) 4. completed: This chapter is more or less finished. Concentrate your effort on the other ones :) If you spot a mistake or typo, improvements are still possible, of course. Important: Don't forget to update a chapter's status, after you have worked on it ;-) When you've got a great idea that would introduce a major change inthe
book's structure, please confer with other editors on the mailinglist
to see what they think about this. Cover ===== If you're good at creating meaningful art, then we need you forcreating
a cool cover image that shows what you can do with Inkscape and is inviting for beginners. Read more about the Cover Manager inBooktype at
http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/_draft/_v/1.0/the-edit-interface/
<http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/_draft/_v/1.0/the-edit-interface/>.
Let us know about your plans on the mailing list (see section about Communication). Styling and Customization ====================== If you know your CSS, you can help by improving the book's styling.You
can read all about customization for different output formats and the front page in the design section of the Booktype manual at http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/formless-content/
<http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/formless-content/>.
For the book to appear on the flossmanuals.net <http://flossmanuals.net> frontpage, the steps outlined here are required: http://write.flossmanuals.net/floss-manuals-workflow/_draft/_v/1.0/how-do-i-make-an-updated-version-of-a-manual/
<http://write.flossmanuals.net/floss-manuals-workflow/_draft/_v/1.0/how-do-i-make-an-updated-version-of-a-manual/>
, section "Publish new details..." License ======= This book is licensed under the Creative Commons Attribution 4.0license
(CC-By 4.0, see https://creativecommons.org/licenses/by/4.0/ <https://creativecommons.org/licenses/by/4.0/>). By contributing to this book, you agree to publish your content under this license. As a contributor, please add your name to the list in the 'About this Book' chapter. This chapter will *always* be in need of new content ;-) Go! === Have fun working on the book at http://write.flossmanuals.net/start-with-inkscape/_edit/# <http://write.flossmanuals.net/start-with-inkscape/_edit/#> You will find a copy of these notes in the 'Notes' tab, and you will find me working on translating French -> English there, in the late evenings (CEST). See you there, Kind 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-docs mailing list Inkscape-docs@lists.sourceforge.net <mailto:Inkscape-docs@lists.sourceforge.net> https://lists.sourceforge.net/lists/listinfo/inkscape-docs <https://lists.sourceforge.net/lists/listinfo/inkscape-docs>
Hey Victor,
so then you get the official welcome :)
Welcome!
Looking forward to see you around, hope we're all going to have some fun on the manual :)
Maren
Am 16.05.2017 um 23:34 schrieb Victor Westmann:
Hi Maren,
I just did.
Cheers,
--Victor Westmann
2017-05-16 13:16 GMT-07:00 Maren Hachmann <maren@...68... mailto:maren@...68...>:
Hi Victor, :) Will you join us there? Maren Am 16.05.2017 um 00:48 schrieb Victor Westmann: > I'm so happy we got to this point! Really happy! Can't believe it we > were able to solve this and finally, start editing this new material!!! ;-D > > Congrats to everyone involved in clearing the way for this to become true. > > Cheers, > > > > --Victor Westmann > > 2017-05-15 15:24 GMT-07:00 Maren Hachmann <maren@...68... <mailto:maren@...68...> > <mailto:maren@...68... <mailto:maren@...68...>>>: > > Hi everyone, > > join us for translating and editing the Inkscape Beginners' manual, > which is based upon Elisa de Castro Guerra's French book "Initiation à > Inkscape" (Original French version available at > https://www.flossmanualsfr.net/initiation-inkscape/ <https://www.flossmanualsfr.net/initiation-inkscape/> > <https://www.flossmanualsfr.net/initiation-inkscape/ <https://www.flossmanualsfr.net/initiation-inkscape/>> - don't translate > this one ;-) ) ! > Thank you, Elisa, for sharing your work and helping with licencing (also > for joining the admins)! > > The plan is to translate the book from French to English (Sylvain and > Hinerangi already did some of the work), and make adjustments as we see > fit, then to make it available for people who only start using Inkscape > - if possible, accessible directly from inside the Inkscape program. > > Here are some notes to get you started (we may tweak processes later, if > we find better ones): > > > Platform usage > ============== > > This book is written at flossmanuals.net <http://flossmanuals.net> <http://flossmanuals.net>, > which is a website that allows > for collaborative editing of books about Free/Libre and Open Source > Software. To learn more about the community that's behind it, please > visit http://www.flossmanuals.org/about-floss-manuals-foundation <http://www.flossmanuals.org/about-floss-manuals-foundation> > <http://www.flossmanuals.org/about-floss-manuals-foundation <http://www.flossmanuals.org/about-floss-manuals-foundation>>. > > The manual for this 'manual writing platform' (which is an instance of > the Booktype software), is available at > http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/ <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/> > <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/ <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/>> > . > > Joining > ======= > > Join the group at > http://write.flossmanuals.net/groups/beginners-manual-for-inkscape/ <http://write.flossmanuals.net/groups/beginners-manual-for-inkscape/> > <http://write.flossmanuals.net/groups/beginners-manual-for-inkscape/ <http://write.flossmanuals.net/groups/beginners-manual-for-inkscape/>> :-) > Also say hi on the docs mailing list (see below, section > "Communication", so we know who is who, and what you can help with. > > Editing > ======= > > IMPORTANT: When you're editing the book, ALWAYS leave a screen either by > clicking on the 'Cancel' or on the 'Save' button. This is because, if > you leave it by just closing the tab in your browser, the chapter will > stay locked and inaccessible for other editors. > > Version > ======= > > This book will refer to the Inkscape 0.92.x series (important for your > screenshots!). > > Writing Style > ============= > > This book is meant as an introduction for people who are not yet > familiar with Inkscape terminology. > > When deciding how to phrase something, think of yourself when you > started to use a vector editor, or think of a teen who you would like to > introduce to the program, and who you would like to enjoy the process, > and to be able to make nice drawings after reading the book. > > Stay on topic, make it easy to understand, and keep the learning curve > shallow. Write less rather than more. Be nice and encouraging to the > reader. There exists another manual that provides the deep, technical > details. We need to keep in mind that it will also be read by people > whose native language is not English. > > Communication > =============== > > Anyone who edits the book can exchange messages, files and snippets via > chat with other users who are online at the same time. > For discussions of wider interest, or when you hit an obstacle, please > subscribe and send a message to the inkscape-docs mailing list at > https://sourceforge.net/p/inkscape/mailman/inkscape-docs/ <https://sourceforge.net/p/inkscape/mailman/inkscape-docs/> > <https://sourceforge.net/p/inkscape/mailman/inkscape-docs/ <https://sourceforge.net/p/inkscape/mailman/inkscape-docs/>> . > > Currently, we have 4 book admins (Elisa, Brynn, CR and me). Admins can > change the book settings, add other admins and create release versions. > > Chapter status > ============== > > Chapters move from one status to the next, when they're being worked on: > > 1. needs translation: > Chapter isn't (fully) translated yet. If you speak both French and > English, this is where your help is needed! This step only requires you > to work on the text. You can ignore any images. > > 2. to be proofed: > Chapter is translated, and needs to be checked by someone other than the > translator, to spot errors and do some polishing. If English is your > native language and you're good with words, grab this job! > > 3. needs images: > The chapter contains images, but those are still French. Either it's > just their file names that need to be changed (Workflow: download image, > rename it on your computer, reupload, change link in the Chapter(s), > provide meaningful alt text, delete French image) or a new screenshot is > needed from the English interface. If you know how to do these things, > please jump right in! > (Hint: all image links follow this scheme: static/image_file.ext) > > 4. completed: > This chapter is more or less finished. Concentrate your effort on the > other ones :) If you spot a mistake or typo, improvements are still > possible, of course. > > Important: Don't forget to update a chapter's status, after you have > worked on it ;-) > > When you've got a great idea that would introduce a major change in the > book's structure, please confer with other editors on the mailing list > to see what they think about this. > > Cover > ===== > > If you're good at creating meaningful art, then we need you for creating > a cool cover image that shows what you can do with Inkscape and is > inviting for beginners. Read more about the Cover Manager in Booktype at > http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/_draft/_v/1.0/the-edit-interface/ <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/_draft/_v/1.0/the-edit-interface/> > <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/_draft/_v/1.0/the-edit-interface/ <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/_draft/_v/1.0/the-edit-interface/>>. > Let us know about your plans on the mailing list (see section about > Communication). > > Styling and Customization > ====================== > > If you know your CSS, you can help by improving the book's styling. You > can read all about customization for different output formats and the > front page in the design section of the Booktype manual at > http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/formless-content/ <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/formless-content/> > <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/formless-content/ <http://sourcefabric.booktype.pro/booktype-16-for-authors-and-publishers/formless-content/>>. > > For the book to appear on the flossmanuals.net <http://flossmanuals.net> > <http://flossmanuals.net> frontpage, the steps > outlined here are required: > http://write.flossmanuals.net/floss-manuals-workflow/_draft/_v/1.0/how-do-i-make-an-updated-version-of-a-manual/ <http://write.flossmanuals.net/floss-manuals-workflow/_draft/_v/1.0/how-do-i-make-an-updated-version-of-a-manual/> > <http://write.flossmanuals.net/floss-manuals-workflow/_draft/_v/1.0/how-do-i-make-an-updated-version-of-a-manual/ <http://write.flossmanuals.net/floss-manuals-workflow/_draft/_v/1.0/how-do-i-make-an-updated-version-of-a-manual/>> > , section "Publish new details..." > > License > ======= > > This book is licensed under the Creative Commons Attribution 4.0 license > (CC-By 4.0, see https://creativecommons.org/licenses/by/4.0/ <https://creativecommons.org/licenses/by/4.0/> > <https://creativecommons.org/licenses/by/4.0/ <https://creativecommons.org/licenses/by/4.0/>>). > By contributing to this book, you agree to publish your content under > this license. > > As a contributor, please add your name to the list in the 'About this > Book' chapter. > This chapter will *always* be in need of new content ;-) > > Go! > === > Have fun working on the book at > http://write.flossmanuals.net/start-with-inkscape/_edit/# <http://write.flossmanuals.net/start-with-inkscape/_edit/#> > <http://write.flossmanuals.net/start-with-inkscape/_edit/# <http://write.flossmanuals.net/start-with-inkscape/_edit/#>> > > You will find a copy of these notes in the 'Notes' tab, and you will > find me working on translating French -> English there, in the late > evenings (CEST). > > See you there, > Kind 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-docs mailing list > Inkscape-docs@lists.sourceforge.net <mailto:Inkscape-docs@lists.sourceforge.net> > <mailto:Inkscape-docs@lists.sourceforge.net <mailto:Inkscape-docs@lists.sourceforge.net>> > https://lists.sourceforge.net/lists/listinfo/inkscape-docs <https://lists.sourceforge.net/lists/listinfo/inkscape-docs> > <https://lists.sourceforge.net/lists/listinfo/inkscape-docs <https://lists.sourceforge.net/lists/listinfo/inkscape-docs>> > >
participants (4)
-
brynn -
Elisa Godoy de Castro Guerra -
Maren Hachmann -
Victor Westmann