docs.krita.org organization and structure for future changes
Open, Needs TriagePublic

Description

Go over the current structure of our docs site and see if there are ways to improve it. For this task, we are going to brainstorm a bit at a higher level with all the different sections. I think before we might do any specific changes or updates, it would be good to get a better picture of what each section should contain and how to link to other sections if needed.

There is currently a page that outlines some of these things: https://docs.krita.org/en/contributors_manual/krita_manual_readme.html

A couple ideas suggestions to get the conversation going:

  1. We don't have a user manual section in the link above. What type of content means "user manual"?
  2. Most of the FAQ is now part of ask.krita.org. There is quite a bit of duplicate content now, so how might want want to handle that?
  3. How do we link to different sections. What if a tutorial would be a good reference when explaining what each animation timeline button does?
  4. Think about different questions that people might have...and what section they should go to answer that. Where should they go if they ask something like "what does this button do" or "is my tablet supported". Also how to take care of different step related things. There are steps that are specific to do one function in Krita "how do I export my animation" vs. longer multi-step questions that combine multiple features "how do I create an animation. The more examples we can give and associate it with a section of the docs site, the easier it will be for documentation writers to know where to put stuff.

The user manual...

we need a place where we can go 'this is how you use this or that', as well as a place where we can list the bare basics of using the program. This is in contrast with the reference manual which is only about 'what does this button do', and maybe some 'how to use this' if it fits within a single page, as well as general concepts which is about topics that are basics to understanding painting, digital or otherwise(hence file formats is in here).

scottpetrovic added a comment.EditedDec 11 2018, 5:09 PM

@woltherav - alright, so you are thinking the user manual needs to do a couple things. Looking at a few pages, I see a pattern we might want to try to follow for all the areas in the user manual.

Potential example for user manual format
https://docs.krita.org/en/user_manual/tag_management.html
This page first spends time describing what something is in Krita...then goes on to explain usage on how to do things with it like create, modify or delete tags that is specific to that area.

Contrast that to these other pages in the user manual which seem to follow a different writing structure and flow:
https://docs.krita.org/en/user_manual/templates.html -- explains a lot of description on what something is...but nothing on how to use it like creating, modifying, or deleting templates

https://docs.krita.org/en/user_manual/working_with_images.html -- Seems to have a lot of general concept information that isn't specific to Krita. Then later goes into more usage on things like image resizing that is specific to Krita.

After spending a bit more time looking at the different pages in the user manual, the different structures for content might be what is confusing to some people (including me). If we make things a bit more consistent in terms of structure, we could always add things at the bottom like "Related Tutorials" or "Related General Concepts" that could link to those areas for further information in people are interested.

Let me know what you think about creating kind of a "template" for the structure of a user manual page. The structure might help people know what to expect when they get in there

emmetoneill added a comment.EditedDec 19 2018, 1:38 AM

Hey all. I spent a few days thinking about this thread.

I think there are a few core questions that all program manuals need to answer: (1) "who is our audience", (2) "what information do they need", and (3) "how, where, and in what order should we present it to them".
Krita's manual is no exception to that, so I think that finding ways to improve it means returning to those questions.

Starting with Q1, who is reading Krita's documentation and why?

  1. New and newish Krita users. There are two subcategories with different hurdles:
    1. "Blank Slate" users who are totally new to the world of digital art.
    2. "Converted" users who are new to Krita, but have experience with other tools.
  2. Intermediate users. These users are familiar or experienced with parts of Krita, but are either:
    1. Searching to see if some specific feature exists.
    2. Confused by how some part of the program works.
    3. Trying to find a canned solution to some issue or bug that they've run into before posting or asking about it.
  3. Prospective contributors and developers. These are people who have various assets or skills, varying degrees of knowledge about Krita, and are interested in getting involved somehow in the project.
    1. People who have design ideas for how they think Krita can be better, but may not have the technical skills to realize them.
    2. Programmers of various technical levels.
    3. Artists and content creators of various skill levels.
    4. Writers, translators, and community-oriented people.
    5. People who are interested in funding Krita's development.

Just starting from there, I think the "user manual" section may be slightly too monolithic.
Basically everyone who comes to read our manual is a user, but the key piece of the puzzle is finding out what kind of user they are, and based on that, which content they are most likely to be interested in.
Overall, in terms of content, I think we really do have most of what we need already, and if there is some kind of flaw in our organization, it's that we aren't doing enough to "direct traffic", so to speak.

So I guess my big picture organizational thought would be to break up our "user manual" into chunks that cater to different types of users. So, something like:

  1. 1. Krita 101 / Krita Primer / Quick Start / Getting Started / New User Guide
  1. 2. Krita 202 / Intermediate User Guide
  1. 3. Krita 303 / Advanced User Guide / Special Features

(I couldn't get the numbered list to behave, so I gave up.)

We already have the Contributor's Manual, which I think should stay separate from these different users manuals.

And, when it comes to the FAQ, it's probably a good idea to keep it, although it might be a good idea to simply have it link to a bunch of questions on the Q&A site - but I'm not sure about that...

And, yes, there's always work to be done in terms of editing, updating, and standardizing our approach to every nook and cranny of the manual, and there may be ways to improve our process to help with that (for example, a major version release task/checklist that we step through, some kind of spreadsheet that can tell us during which version each page was last updated, etc.).

Anyway, that ended up being a lot of writing, but the broad idea would be to break our user manual into a couple of different sections that are geared towards different 'levels' of users.
Doing so would be mostly organizational, but I think there would also be some content implications or burdens so the question is whether it's worth the time and effort.

Well, we did have a determination of demographics and target audience, but I guess that'd on the list of things noone reads. I personally stayed away from 'beginner' 'intermediate' 'advanced', as it is often very hard to determine where things belong in the hierarchy.

Like, I am neutral to it really, I am just saying that someone else will need to decide where things need to go in the hierarchy. I just cannot do it.

@emmetoneill I am not sure what you are proposing exactly. Are you proposing that we remove the reference guide, general concepts, and tutorials area. Or are you proposing to move all that stuff into the user manual under a beginner, intermediate, and advanced areas. The way I am reading your comment, the "big picture" appears to only talk about the user manual. I don't see any references to our other areas like tutorials, reference manual, or general concepts areas and how those fit in.

Maybe what we need to do is spend a day at a Krita sprint on determining how the manual drills down(from novice to expert), much like we've done for the resource rewrite. We can then get some input from the available artists on how they perceive the manual, and then do a reorganisation then.

I think the reference manual does need to be seperate. Not sure about tutorials or general concepts at this point.