Create Task
Maniphest T10178

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

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.
woltherav added a comment.Dec 11 2018, 3:04 PM

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.Dec 19 2018, 1:38 AM
This comment was removed by emmetoneill.
woltherav added a comment.Dec 19 2018, 2:11 PM

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.

scottpetrovic added a comment.Dec 19 2018, 5:30 PM

@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.

woltherav added a comment.Dec 20 2018, 2:34 PM

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.