3 questions about current documentation practices

I’m running through the documentation and have been developing some questions that I’m not sure have been covered formally.

  • I see mixed usage of contractions, e.g. “you are” and “you’re”. Can we decide a preference? I always prefer conciseness so the reader gets to what they want faster, so I’m in favor of contractions.

  • I see mixed usage of Title Case and Sentence case used for page and section titles, e.g. “Creating a New Document” and “How to use brushes” both appear in starting_krita.rst. Can we decide a preference? I prefer the more modern trend of sentence casing; in lists and paragraphs heavy with page links, it could improve readability.

  • Do we say Krita Manual or Krita manual? I see the former more often than the latter, but I prefer the latter.

1 Like

The difference between contracted and full form can be useful for contrast and emphasis and I don’t think it’s a good idea to be too prescriptive with personal style at that level of detail.

Any mixed use of case, font, bold, etc in different places is very confusing if you’re trying to find your way around a document so I think it would be a good idea to standardise on those aspects.

‘Krita Manual’ vs ‘Krita manual’ Does that depend on context and location? I haven’t noticed that one but I’m sure there are many usage differences of that type and it would be quite a job to standardise them all if they are context/location dependent.

If you’re volunteering then good luck because it’s quite a task :slight_smile:

I have to admit I’ve always avoided going too much into detail regarding style because it makes it much harder for people inexperienced into contributing to actually contribute (A style guide can very often lead to a ‘oh, I am not good enough to contribute, I have no idea what a passive sentence is’, while said person might just have a knack for explaining things), but I understand this might be confusing for people trying to remove typos and grammar errors.

The most I do is to try and have the English corrected and get contributors to avoid ‘comic book dialogue’ where every other sentence is bolded and/or ended with an exclamation mark.

So for…

  1. This is very specific to the sentence. Contracting or not contracting, like Ahab says, changed emphasis by virtue of changing the rhythm of the sentence, and thus not something I would want to poke at too much.
  2. This is caused by the fact that the actions in Krita are called ‘New Document’. I am uncertain what is best here, because on one hand you want to familiarize the reader with the actions and verbiage as they appear in the program and thus not change the gestalt of the words too much, but on the other hand, it doesn’t make sense as English.
  3. I have gone back and forth on this one. On one hand it is the manual of krita, on the other hand Krita Manual is what I put on the epub cover.

A part of me has been wondering if we can use gitlab’s CI system (that is, a way to do some machinated checks on contributions) to run language tool on contributions and thus have a more unified style, but at that moment we’ll need to make decisions on what is sensible for the style of the manual too. :smiley:

2 Likes

I’m not an expert on this subject, but I suppose Krita Manual is more correct, as it is the title of an electronically published work.

Since point #2 in the answers to this question are trending towards Title Casing, I agree, as that is both logical and coherent with Title Casing. So at least in my edits I’ll use both Krita Manual and that casing style. Thanks.

1 Like

If you need any help in submitting your changes please let me know. I hope you have found the repository address for making contribution.

1 Like

Oh certainly, thanks. I have it forked locally and all. I’m also a dev.