Difference between revisions of "Google Season of Docs 2024"

From Inkscape Wiki
Jump to navigation Jump to search
m (Corrected current version, typo fix)
Line 6: Line 6:
==About your organisation==
==About your organisation==


Inkscape (current version 1.3.2, first released in 2003) is a GPL-licensed program for creating artwork using SVG as its native format. Inkscape is widely used to create artwork (web graphics, logos, book illustrations, comics, games, and scientific publications) that require scalability. It is available for Linux, Windows and MacOS with millions of users.
Inkscape (current version 1.3.2, first released in 2003) is a GPL-licensed program for creating artwork using SVG as its native format. It is available for Linux, Windows and macOS, and is the only major vector graphics software (open-source or proprietary) available on Linux. Our millions of users are scientists, designers, engineers, makers and hobbyists who create scientific publications, web graphics, logos, book illustrations, comics, game assets, or technical drawings and sketches - any type of graphics that requires scalability. Our contributors have a wide range of backgrounds, similar to our users, with a healthy mix of long-term and drive-by contributions.


Inkscape is a member of the Software Freedom Conservancy.
Inkscape is a member of the Software Freedom Conservancy.
Line 12: Line 12:
===Your project's problem===
===Your project's problem===
Inkscape is a very large and complex program. Many books, on-line tutorials, and videos are available to help people to learn to use Inkscape. What is missing, though, is an up-to-date, complete manual that covers all parts of Inkscape. The most complete on-line manual, [http://tavmjong.free.fr/INKSCAPE/MANUAL/html/index.html Inkscape: Guide to a Vector Drawing Program] (freely available on the web and linked to from Inkscape itself), is woefully out-of-date. The last complete update of this manual was done in 2011, with a partial update in 2017. Despite that, Inkscape users still find it quite useful (as documented by the number of times users are directed to it on social media).
Inkscape is a very large and complex program. Many books, on-line tutorials, and videos are available to help people to learn to use Inkscape. What is missing, though, is an up-to-date, complete manual that covers all parts of Inkscape. The most complete on-line manual, [http://tavmjong.free.fr/INKSCAPE/MANUAL/html/index.html Inkscape: Guide to a Vector Drawing Program] (freely available on the web and linked to from Inkscape itself), is woefully out-of-date. The last complete update of this manual was done in 2011, with a partial update in 2017. Despite that, Inkscape users still find it quite useful (as documented by the number of times users are directed to it on social media).
Your project's scope.


=== Your project's scope ===
This project will bring the on-line manual up-to-date:
This project will bring the on-line manual up-to-date:
*Update the tutorials.
*Update the tutorials.
Line 106: Line 106:


*This project will not create tutorial pages that incorporates multiple tools. (This comes after the project ends)
*This project will not create tutorial pages that incorporates multiple tools. (This comes after the project ends)
For this project, we already have a good candidate for the technical writer role. Documentation team lead @Moini and Project Leadership Committee member @joneuhauser are available as mentors.


===Measuring your project's success===
===Measuring your project's success===

Revision as of 19:56, 29 March 2024

GSoD is a Google program to connect professional technical writers with open source projects.

https://developers.google.com/season-of-docs?hl=de

On this page, we can collect ideas for our participation in the 2024 round of GSoD. Add your ideas by creating a new proposal!

About your organisation

Inkscape (current version 1.3.2, first released in 2003) is a GPL-licensed program for creating artwork using SVG as its native format. It is available for Linux, Windows and macOS, and is the only major vector graphics software (open-source or proprietary) available on Linux. Our millions of users are scientists, designers, engineers, makers and hobbyists who create scientific publications, web graphics, logos, book illustrations, comics, game assets, or technical drawings and sketches - any type of graphics that requires scalability. Our contributors have a wide range of backgrounds, similar to our users, with a healthy mix of long-term and drive-by contributions.

Inkscape is a member of the Software Freedom Conservancy.

About your project: Update INKSCAPE – Guide to a Vector Drawing Program

Your project's problem

Inkscape is a very large and complex program. Many books, on-line tutorials, and videos are available to help people to learn to use Inkscape. What is missing, though, is an up-to-date, complete manual that covers all parts of Inkscape. The most complete on-line manual, Inkscape: Guide to a Vector Drawing Program (freely available on the web and linked to from Inkscape itself), is woefully out-of-date. The last complete update of this manual was done in 2011, with a partial update in 2017. Despite that, Inkscape users still find it quite useful (as documented by the number of times users are directed to it on social media).

Your project's scope

This project will bring the on-line manual up-to-date:

  • Update the tutorials.
  • Update chapters on each part of Inkscape's interface.
  • Create new chapters for new tools (The Shape Builder and Pages).
  • Create new sections for new dialogs.
  • Move the on-line website from the Author's personal site to Inkscape's official site. (Apart from looking more official, this would enable use of https, making indexing by Google easier, as well as provide more reliable hosting).

Out-of-scope work:

  • Update or include tutorials reserved under contract to the publisher of the printed book.

As a side benefit, revising the manual will probably uncover regressions and bugs with newer Inkscape versions, which we can then track and fix.

The author of the original manual is available to write the update with review by volunteers.

Measuring your project's success

The number of times that users access the on-line book would be an indication of the success of the project, however, Inkscape's long term commitment to user's privacy makes this difficult. A simpler measure of the success of the project would be the number of sections updated.

Timeline

Updating the full manual is a year-long part-time project, however, Inkscape would still benefit greatly if a significant fraction of the manual was updated. The target for this program would be to update half the book, focusing on the most pressing parts.

Dates

Dates Action Items
May Preliminary work (Gitlab site, continue with DocBook or switch to another source format, update tooling, etc.)
June-July Update introductory text and tutorials.
August Create new chapters for Shape tool and Page tool.
September-November Update individual chapters, prioritized by the Inkscape community.

Project Budget

Budget item Amount Running Total Notes/justifications
Technical writer, manual update. 12500.00 12500.00
Volunteer stipends 500.00 13500.00 2 volunteer stipends x 500 each
Software Freedom Conservancy fee 1500.00 15000.00 Inkscape is a member of SFC (as suggested also on the GSoD documentation), and due to our fiscal sponsorship agreement, the SFC takes a 10% cut of the gross income of the project.
TOTAL 15000.00

Additional information

  • Previous experience with technical writers or documentation: Inkscape maintains a website with user and developer documentation. Keeping this website current is a one of the most difficult problems we face. All contributions have been made by volunteers.
  • Previous participation in Google Season of Docs, Google Summer of Code or others: Inkscape has participated in Google Summer of Code every year except for one, since its inception. GSoC students have made significant contributions to Inkscape.
  • Disclosure: The manual’s author is a long-time Inkscape contributor and is a member of Inkscape's Project Leadership Committee.

About your project: Update Inkscape's Beginners' guide

Inkscape has an official user manual hosted at ReadTheDocs, which covers basic usage of Inkscape, with guides on drawing tools, colors, text, etc. However the manual is currently targeting Inkscape 1.1, while the latest version is 1.3.2. In between, there are a number of undocumented changes, such as the new Live Path Effects dialog, on-canvas pattern editing, spiro and BSpline path support, multiple pages support, shape builder and more. Other parts of the manual (shortcuts, icons, etc.) also need updating to reflect the current user interface. These missing functionalities and outdated instructions confuse newcomers, which the manual primarily targets. Additionally, the manual lacks consistency in the colors and resolutions used in figures and the comprehensiveness of tool descriptions. The manual also lacks a contribution guide, including how to contribute translations, which makes it difficult for new contributors to help with user-facing documentation.

Your project's scope

The Inkscape Beginner’s Guide update project will:

  • Review the current guide and mark all places that needs an update within a Gitlab issue (with sub-issues if needed).
  • Add pages and paragraphs for new tools in appropriate locations, such as the Pages tool and the Measure tool under 'Useful Techniques', the filter editor dialog in the 'Filters' page, the new color wheel in the 'Fill and Stroke' page, etc.
  • Update parts of the guide according to the aforementioned issue.
  • Create a 'style guide' in the README documenting the tone of voice of the guide, colors and proportions used for figures. Include information about the translation process in the contributors guide, and document language-specific details (such as the use of “you” and “we” in English).
  • Re-capture screenshots of the current interface and redraw figures according to the style guide.
  • Edit the guide to make wording and grammar consistent.
  • Work with the inkscape-docs team to update the documentation on the ReadTheDocs site.

Work that is out-of-scope for this project:

  • This project will not create tutorial pages that incorporates multiple tools. (This comes after the project ends)

For this project, we already have a good candidate for the technical writer role. Documentation team lead @Moini and Project Leadership Committee member @joneuhauser are available as mentors.

Measuring your project's success

The Inkscape forum and chatroom currently recieves a number of questions per day, some of which are related to new features, therefore we aren’t able to refer them to the manual. The improved documentation would give people a definitive source to point to when answering questions, and we hope it helps people understand the tools further in addition to solving the problem. We also think that the contribution guide would help aspiring manual writers and translators make their first contribution, which hopefully makes them stick around and contribute further.

We will track the number of total visitors monthly, and the amount of merge requests and issues opened quarterly after the manual is updated.

We will consider the project successful if, after publication of the new manual:

  • The number of individual visitors (indicated by ReadTheDocs) increases by 15%
  • Translations for at least one additional language is being worked on
  • The number of contributors who have made >3 contributions increases by 10% (beginning the quarter after the documentation is published)

Timeline

The project will take approximately 6 months to complete. We’ll spend a month creating the style guide and documenting required changes and additions, 4 months editing and creating pages, and 1 month revising all aspects of the manual adhering to the style guide.

Dates Action Items
May Create style guide and document required changes and additions
June - September Edit and create pages
October Revise the text and figures
November Project completion

Project Budget

Budget item Amount Running Total Notes/justifications
Technical writer, manual update. 12500.00 12500.00
Volunteer stipends 500.00 13500.00 2 volunteer stipends x 500 each
Software Freedom Conservancy fee 1500.00 15000.00 Inkscape is a member of SFC (as suggested also on the GSoD documentation), and due to our fiscal sponsorship agreement, the SFC takes a 10% cut of the gross income of the project.
TOTAL 15000.00

Additional information

  • Previous experience with technical writers or documentation: Inkscape maintains a website with user and developer documentation. Keeping this website current is a one of the most difficult problems we face. All contributions have been made by volunteers.
  • Previous participation in Google Season of Docs, Google Summer of Code or others: Inkscape has participated in Google Summer of Code every year except for one, since its inception. GSoC students have made significant contributions to Inkscape.