- Use American English if possible.
- We use American English in the manual, in accordance to Krita's UI being American English by default.
- Keep the language polite, but do not use academic language.
- 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.
- Avoid using gifs.
- 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.
- Keep it translation compatible
- This means using the userbase typography rules. Notable thing include not using top level headers, but starting at h2 level, or using bold to indicate program names.
Regarding photos and paintings.
- 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 replacement for photo retouching, which really isn't the focus.
- 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.
- Photos can still be used for photobashing and the like, but only if it's obviously used in the context of photobashing.
Regarding images in general:
- Avoid text in the images and use the caption instead.
- 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.
- Try to make your images high quality/cute. Let's give people the idea that they are using a program for drawing!
Editing manual pages
If you think the manual is outdated, please edit it. If you feel uncertain about edits, either post in the discussion page, or contact us on the forums or the IRC!
General Page structure
For each page we use the following structure:
- Introduction - what is this page about (doesn't need a header)
- Reference - What is the bare-bones, what does each button do? (Only applicable for function-specific pages)
- Hotkeys and stick-keys are put here as well. A key needs to be surrounded with <keycap>key</keycap> due to the translation-rules.
- Use-cases and tutorials - Here you give an indication of use-cases.
- External links - if there's pages explaining the concept further or referencing them, you can add them here.
- Navigation links - these need to be added to many pages, but you can refer to pages where it exists, so that users are encouraged to move along.
Rewriting a page
If you would like to completely rewrite a page, contact us in the IRC or on the forum, and tell us why it needs to be completely rewritten, and give your indication of an outline of what you're gonna write. We need the outline to determine whether the page is that out-dated, and to give you tips to make your life easier.
Writing tutorial pages
Porting a tutorial to the Userbase Manual
First and foremost, ask the person whose tutorial it is for permission, as you may have noticed, the whole userbase wiki has a standard creative commons license. If you port a tutorial, this license is also considered applied to that text, which is illegal without the original author's consent.
Always link to the original page it was ported from, so that everyone involved it completely clear about how it ended up there.
This page was last modified on 6 January 2016, at 16:59. Content is available under Creative Commons License SA 4.0
unless otherwise noted.