Differential D13164 Diff 35000 contributors_manual/krita_manual_readme.rst

Changeset View

Standalone View

contributors_manual/krita_manual_readme.rst

Show All 11 Lines
12	.. _krita_manual_contributors_guide:	12		.. _krita_manual_contributors_guide:
13		13
14	===============================	14		===============================
15	Krita Manual Contribution Guide	15		Krita Manual Contribution Guide
16	===============================	16		===============================
17		17
18	Welcome to our new documentation!	18		Welcome to our new documentation!
19		19
20	We're moving from userbase.kde.org to docs.krita.org, then we moved from mediawiki to sphinx. This latter change is because sphinx allows us to handle translations much better than mediawiki can.	20		We're moving from userbase.kde.org to docs.krita.org, then we moved from Mediawiki to Sphinx. This latter change is because Sphinx allows us to handle translations much better than Mediawiki can.
21		21
22	The manual will include:	22		The manual will include:
23		23
24	A reference manual for Krita	24		A reference manual for Krita
25	This one is probably what everyone is expecting when they type in docs.krita.org. Dry, basic, 'what does this button do' type of information.	25		This one is probably what everyone is expecting when they type in docs.krita.org. Dry, basic, 'what does this button do' type of information.
26	General concept tutorials.	26		General concept tutorials.
27	We've found over the past two years that for certain of users, a reference manual, even with some examples, just isn't enough. The manual should provide fast and concise explanations for things, and provide a basic workflow for preparing an image for the web. But we also have found that certain concepts, such as color management and layer handling is far more advanced in Krita than that the average artist is used to. Krita is free and many of its users will not have formal training in digital artwork. So there's no pre-existing artist-focused knowledge on how to use color management or filter layers. In addition there are systems that are unique to Krita, for example the brush system, the transform masks, the alpha inheritance and the perspective assistants. Finally, there are users who aren't familiar with even standard painting workflows, and are not flexible enough to understand how to port a tutorial for Sai or Photoshop to Krita.	27		We've found over the past two years that for certain types of users, a reference manual, even with some examples, just isn't enough. The manual should also provide fast and concise explanations for things, and provide a basic workflow for preparing an image for the web. We also have found that certain concepts, such as color management and layer handling are far more advanced in Krita than the average artist is used to. Krita is free and many of its users will not have formal training in digital artwork. So there is no pre-existing artist-focused knowledge on how to use color management or filter layers. In addition there are systems that are unique to Krita, for example the brush system, the transform masks, the alpha inheritance and the perspective assistants. Finally, there are users who aren't familiar with even standard painting workflows, and are not flexible enough to understand how to port a tutorial for Sai or Photoshop to Krita.
28	A list of known tutorials and video tutorials	28		A list of known tutorials and video tutorials
29	Apparantly, one of the great things about Krita's team is how we connect with artists and acknowledge that they're doing cool stuff. The same should count for tutorials, especially because there's ways of using Krita and ways of approaching painting that are unique and we should encourage people to share their knowledge.	29		Apparently, one of the great things about Krita's team is how we connect with artists and acknowledge that they're doing cool stuff. The same should count for tutorials, especially because there are ways of using Krita and ways of approaching painting that are unique and we should encourage people to share their knowledge.
30	Contributors Manual	30		Contributor's Manual
31	Krita is (free) open source software, which makes us effectively a community project, with dozens of volunteers pitching in to make it better. That of course requires we keep track of manuals and howto's for new volunteers to come in and help us. The various places we've done this have been rather spread out, and are often under maintained. The contributor's manual is an attempt to solidify all the information. It is therefore very technical in places.	31		Krita is (free) open source software, which makes us effectively a community project, with dozens of volunteers pitching in to make it better. This, of course, requires we keep track of manuals and howto's for new volunteers to come in and help us. The various places we've done this have been rather spread out, and are often under maintained. The contributor's manual is an attempt to solidify all the information. It is therefore very technical in places.
32	krita.org tutorials	32		krita.org tutorials
33	There's been a bunch of tutorials on the krita.org and the krita-foundation.tumblr.com, the former focussing on explaining how to use a new feature and the later stimulated by user request.	33		There have been a bunch of tutorials on the krita.org and the krita-foundation.tumblr.com, the former focusing on explaining how to use a new feature and the later stimulated by user request.
34	FAQ	34		FAQ
35	This one is already online and a merger of the different FAQs that we had. It's currently being translated and we hope to keep this one the primary one to update.	35		This one is already online and a merger of the different FAQs that we had. It's currently being translated and we hope to keep this one the primary one to update.
36		36
37	For first timers	37		For first timers
38	----------------	38		----------------
39		39
40	Unlike Mediawiki, sphinx works more like how we create code.	40		Unlike Mediawiki, Sphinx works more like how we create code.
41		41
42	First things first, you would want to talk to us! For this you can either go to the `IRC on krita.org (#krita on freenode.org) <https://krita.org/en/irc/>`_, or, more importantly, make an account at `identity.kde.org <https://identity.kde.org/>`_. The account you make at identity can be used to both access the forum as well as the phabricator, where we organise Krita development.	42		First things first, you will want to talk to us! For this you can either go to the `IRC on krita.org (#krita on freenode.org) <https://krita.org/en/irc/>`_, or, more importantly, make an account at `identity.kde.org <https://identity.kde.org/>`_. The account you make at identity can be used to both access the forum as well as the phabricator, where we organise Krita development.
43		43
44	If you have no idea where to begin, make a kde identity account and make a post on `the forum <https://forum.kde.org/viewforum.php?f=136>`_.	44		If you have no idea where to begin, make a Kde identity account and make a post on `the forum <https://forum.kde.org/viewforum.php?f=136>`_.
45		45
46	Sphinx works by writing simple text files with reStructuredText mark up, and then it takes those text files and turns them into the manual. We keep track of changes in the manual by putting them into a version control system called :program:`Git`.	46		Sphinx works by writing simple text files with reStructuredText mark up, and then it takes those text files and turns them into the manual. We keep track of changes in the manual by putting them into a version control system called :program:`Git`.
47		47
48	Making changes	48		Making changes
49	~~~~~~~~~~~~~~	49		~~~~~~~~~~~~~~
50		50
51	Because we use Git, there's only a few people who can put things into the git, so if you want to make changes you will need to put it up for review.	51		Because we use Git, there are only a few people who can put things into the git, so if you want to make changes you will need to put it up for review.
52		52
53	If you are not familiar with Git	53		If you are not familiar with Git
54	^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^	54		^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
55		55
56	1. Get the source text.	56		1. Get the source text.
57		57
58	Save a copy of the text as it existed originally.	58		Save a copy of the text as it existed originally.
59		59
Show All 11 Lines		69	5. Upload the zip on phabricator.
71	1. First, go to phabricator.kde.org and log in with you identity account.	71		1. First, go to phabricator.kde.org and log in with you identity account.
72	2. Go to the `manual project board <https://phabricator.kde.org/project/view/135/>`_ and there create a new task.	72		2. Go to the `manual project board <https://phabricator.kde.org/project/view/135/>`_ and there create a new task.
73	3. Explain what you did and use drag and drop to move the zip file to the input textbox. That should upload it. We will also need the email address you associate with your kde identity account.	73		3. Explain what you did and use drag and drop to move the zip file to the input textbox. That should upload it. We will also need the email address you associate with your kde identity account.
74	4. Then, if the changes are accepted, someone with commit access will unpack those files into the manual folder and push the differences using the mail address.	74		4. Then, if the changes are accepted, someone with commit access will unpack those files into the manual folder and push the differences using the mail address.
75		75
76	If you are familiar with Git	76		If you are familiar with Git
77	^^^^^^^^^^^^^^^^^^^^^^^^^^^^	77		^^^^^^^^^^^^^^^^^^^^^^^^^^^^
78		78
79	1. get the source.	79		1. Get the source from `Krita.org Documentation Website <https://phabricator.kde.org/source/websites-docs-krita-org/>`_ using :program:`Git` clone
80	2. Make changes	80		2. Make changes
81	3. Build locally (optional)	81		3. Build locally (optional)
82	4. Generate a git diff.	82		4. Generate a git diff.
83		83
84	Go to the source directory in your terminal and write ``git diff > ../mydiff.diff`` this will make a diff file in the folder above.	84		Go to the source directory in your terminal and write ``git diff > ../mydiff.diff`` this will make a diff file in the folder above.
85		85
86	5. Create a review request on phabricator	86		5. Create a review request on phabricator
87		87
Show All 13 Lines
101	We cannot talk about a demographic in the sense that we know all Krita users are 55 year old men. Krita is used by a hugely different amount of people, and we are actually kind of proud that we have such a varied userbase.	101		We cannot talk about a demographic in the sense that we know all Krita users are 55 year old men. Krita is used by a hugely different amount of people, and we are actually kind of proud that we have such a varied userbase.
102		102
103	Despite that, we know a couple of things about our users:	103		Despite that, we know a couple of things about our users:
104		104
105	* They are artists. This is explicitly the type of users that we target.	105		* They are artists. This is explicitly the type of users that we target.
106		106
107	* Therefore, we know they prefer pretty pictures.	107		* Therefore, we know they prefer pretty pictures.
108	* They are visual.	108		* They are visual.
109	* And that they are trying to achieve pretty pictures.	109		* They are trying to achieve pretty pictures.
110		110
111	Therefore, the implicit goal of each page would be to get the feature used for pretty pictures.	111		Therefore, the implicit goal of each page would be to get the feature used for pretty pictures.
112		112
113	Other than that, we've observed the following groups:	113		Other than that, we've observed the following groups:
114		114
115	* High-school and college students trying out drawing software for illustrations. These usually have some previous experience with drawing software, like Painttool Sai or Photoshop, but need to be introduced to possibilities. This group's strength is that they share a lot of information with each other like tips and tricks and tutorials.	115		* High-school and college students trying out drawing software for illustrations. These usually have some previous experience with drawing software, like Painttool Sai or Photoshop, but need to be introduced to possibilities in :program:`Krita`. This group's strength is that they share a lot of information with each other like tips and tricks and tutorials.
116	* Professionals, people who earn their money with digital drawing software. The strength of this group is that they have a lot of know-how and are willing to donate to improve the program. These come in two types:	116		* Professionals, people who earn their money with digital drawing software. The strength of this group is that they have a lot of know-how and are willing to donate to improve the program. These come in two types:
117		117
118	* Non technical professionals. These are people who do not really grasp the more mathematical bits of a piece of software, but have developed solid workflows over the years and work with software using their finely honed instincts. These tend to be illustrators, painters and people working with print.	118		* Non technical professionals. These are people who do not really grasp the more mathematical bits of a piece of software, but have developed solid workflows over the years and work with software using their finely honed instincts. These tend to be illustrators, painters and people working with print.
119	* Technical professionals. These are people who use Krita as part of a pipeline, and care about the precise maths and pixel pushing. These tend to be people working in the games and VFX industry, but occasionally there's a scientist in there as well.	119		* Technical professionals. These are people who use :program:`Krita` as part of a pipeline, and care about the precise maths and pixel pushing. These tend to be people working in the games and VFX industry, but occasionally there's a scientist in there as well.
120		120
121	* Adult and elderly hobbyists. This group doesn't know much about computers, and they always seem to get snagged on that one little step missing from a tutorial. Their strength as a group is that they adapt unconventional workflows from real life that the student wouldn't know about and the professional has no time for and create cool stuff with that, as well as that they have a tempering effect on the first group in the larger community.	121		* Adult and elderly hobbyists. This group doesn't know much about computers, and they always seem to get snagged on that one little step missing from a tutorial. Their strength as a group is that they adapt unconventional workflows from real life that the student wouldn't know about and the professional has no time for and create cool stuff with that, as well as that they have a tempering effect on the first group in the larger community.
122		122
123	From these four groups...	123		From these four groups...
124		124
125	* there's only one that is technical. Which is why we need the concept pages, so that we can create a solid base to write our manual texts on top of.	125		* there's only one that is technical. Which is why we need the concept pages, so that we can create a solid base to write our manual texts on top of.
126	* three of them likely have previous experience with software and may need migration guides and be told how.	126		* three of them likely have previous experience with software and may need migration guides and be told how.
127	* two of them need to know how to get Krita to cooperate with other software.	127		* two of them need to know how to get Krita to cooperate with other software.
128	* two of them have no clue what they are doing and may need to be guided through the most basic of steps.	128		* two of them have no clue what they are doing and may need to be guided through the most basic of steps.
129		129
130	From that we can get the followig rules:	130		From that we can get the following rules:
131		131
132	General	132		General
133	~~~~~~~	133		~~~~~~~
134		134
135	Use American English if possible.	135		Use American English if possible.
136	We use American English in the manual, in accordance to Krita's UI being American English by default.	136		We use American English in the manual, in accordance to Krita's UI being American English by default.
137	Keep the language polite, but do not use academic language.	137		Keep the language polite, but do not use academic language.
138	As a community, we want to be welcoming to the users, so we try to avoid language that is unwelcoming. Swearing is already not condoned by KDE, but going to the far other end, an academic style where neither writer nor reader is acknowledged might give the idea that the text is far more complex than necessary, and thus scare away users.	138		As a community, we want to be welcoming to the users, so we try to avoid language that is unwelcoming. Swearing is already not condoned by KDE, but going to the far other end, an academic style where neither writer nor reader is acknowledged might give the idea that the text is far more complex than necessary, and thus scare away users.
139	Avoid using gifs.(up to debate)	139		Avoid using gifs (open for debate)
140	The reason is that people with epilepsy may be affected by fast moving images. Similarly, gifs can sometimes cary too much of the burden of explanation. If you can't help but use gifs, at the least notify the reader of this in the introduction of the page.	140		The reason is that people with epilepsy may be affected by fast moving images. Similarly, gifs can sometimes carry too much of the burden of explanation. If you can't help but use gifs, at the least notify the reader of this in the introduction of the page.
141	Keep it translation compatible	141		Keep it translation compatible
142	This consists of using svg for infographics, and using the appropriate markup for given text.	142		This consists of using svg for infographics, and using the appropriate markup for given text.
143		143
144	Regarding photos and paintings	144		Regarding photos and paintings
145	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~	145		~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
146		146
147	* I would like to dis-encourage photos and traditional paintings in the manual if they are not illustrating a concept. The reason is that it is very silly and a little dishonest to show Rembrand's work inside the Krita GUI, when we have so many modern works that were made in Krita. All of the pepper&carrot artwork was made in Krita and the original files are available, so when you do not have an image handy, start there. Photos should be avoided because Krita is a painting program. Too many photos can give the impression Krita is trying to be a solution for photo retouching, which really isn't the focus.	147		* I would like to discourage photos and traditional paintings in the manual if they are not illustrating a concept. The reason is that it is very silly and a little dishonest to show Rembrand's work inside the Krita GUI, when we have so many modern works that were made in Krita. All of the pepper&carrot artwork was made in Krita and the original files are available, so when you do not have an image handy, start there. Photos should be avoided because Krita is a painting program. Too many photos can give the impression Krita is trying to be a solution for photo retouching, which really isn't the focus.
148	* Of course, we still want to show certain concepts in play in photos and master paintings, such as glossing or indirect light. In this case, add a caption that mentions the name of the painting or the painter, or mention it's a photograph.	148		* Of course, we still want to show certain concepts in play in photos and master paintings, such as glossing or indirect light. In this case, add a caption that mentions the name of the painting or the painter, or mention it's a photograph.
149	* Photos can still be used for photobashing and the like, but only if it's obviously used in the context of photobashing.	149		* Photos can still be used for photobashing and the like, but only if it's obviously used in the context of photobashing.
150		150
151	Regarding images in general	151		Regarding images in general
152	~~~~~~~~~~~~~~~~~~~~~~~~~~~	152		~~~~~~~~~~~~~~~~~~~~~~~~~~~
153		153
154	* Avoid text in the images and use the caption instead. Ỹou can do this with the figure directive.	154		* Avoid text in the images and use the caption instead. You can do this with the figure directive.
155	* If you do need to use text, make either an SVG, so the text inside can be manipulated easier, or try to minimize the amount of text.	155		* If you do need to use text, make either an SVG, so the text inside can be manipulated easier, or try to minimize the amount of text.
156	* Try to make your images high quality/cute. Let's give people the idea that they are using a program for drawing!	156		* Try to make your images high quality/cute. Let's give people the idea that they are using a program for drawing!
157		157
158	Other	158		Other
159	-----	159		-----
160		160
161	For restructured text conventions, check :ref:`krita_markup_conventions`.	161		For restructured text conventions, check :ref:`krita_markup_conventions`.