search

OpenShot / openshot-qt

OpenShot Video Editor is an award-winning free and open-source video editor for Linux, Mac, and Windows, and is dedicated to delivering high quality video editing and animation solutions to the world.
http://www.openshot.org
Other
4.25k stars 529 forks source link

Call for Volunteers: Documentation updates #2989

Closed ferdnyc closed 2 years ago

ferdnyc commented 5 years ago

For the next release of OpenShot (whichever and whenever that should be), one of the still-unaddressed needs is documentation.

The manual was mostly written in 2017, with only very minor updates since then. (The last new documentation written was the EDL / XML import and export docs, added on 2019-05-25 by @jonoomph in commit b1422e1a2bdedd5f56b4aca6b1e15d90ef14e78a.)

Documentation needs (working list)

Volunteers welcome!

Any volunteers who'd be interested in helping to improve the manual, both directly (writing documentation) and indirectly (soliciting, organizing, and copyediting contributions from developers) would be greatly appreciated.

Writing and editing OpenShot documentation

The source files for the manual are all found in the project repository (the doc/ directory), the preferred method for submitting edits would be via GitHub Pull Request but we can make accommodations for anyone who'd like to contribute but isn't familiar with version-control systems like Git.

Generating a local copy of the manual requires only the Python-based Sphinx documentation system and the Sphinx RTD theme, which can be installed via pip3 install sphinx sphinx-rtd-theme or using most package managers. I can provide support to anyone who'd like to contribute and needs help with installing and using Sphinx.

MBB232 commented 4 years ago

I am not a programmer, but I saw your call and I thought I'd help out by updating a few screenshots and see how far I get. I've seen enough tutorials and ran into a few issues the last weeks, so I thought I knew a few places of the manual that could use some improvement.

Sure, it's been a while since I last played with HTML 4, but how hard could it be? That was a few hour ago. Turns out that Sphinx you suggest is apparently not a WYSIWYG editor but a scripting tool for .rst files, which uses it's own markup syntax. (On the upside, no issues with font types/size. )

And this github is apparently not as click-and upload as the bugtracker, but uses text commandos for every action. (However I have not yet found the command line in the web interface). It has been educational, but demotivating.

Tutorials that have helped so far:

What I have not found are the standards for the manual. Most pictures are .jpg, are (animated) gif ok too? What compression level/file size do you want? You use green arrows and black numbers in circles to point things out. Do you have color numbers for them? Most screenshots seem to be 4:3, are 16:9 screenshots ok too? Are there other requirements to keep in mind?

There are a lot of explanations and solutions available on the reddit help and here in the github tracker. Can any be re-used without asking or will everything have to be re-done? (Do you have a a license to everything uploading here, which of the users belong to the project and will agree to re-use of their screenshots and help?)

ferdnyc commented 4 years ago

I am not a programmer, but I saw your call and I thought I'd help out by updating a few screenshots and see how far I get.

That sounds like a great idea, @MBB232 — thanks! I'll try to help however I can.

Sure, it's been a while since I last played with HTML 4, but how hard could it be? That was a few hour ago. Turns out that Sphinx you suggest is apparently not a WYSIWYG editor but a scripting tool for .rst files, which uses it's own markup syntax. (On the upside, no issues with font types/size. )

Yeah, Sphinx (actually, ReST in general) was started as a tool for Python code, allowing documentation to be embedded directly into source code, then extracted and formatted for more comfortable reading. And like any tool built by programmers for their own use, it's incredibly flexible, though most of that flexibility requires delving into the code.

I'm actually not aware of any WYSIWYG for reST files, which kind of makes sense given the origins. Since the documentation can be extracted from source code, the best way to write it is in source form. Plus, WYSIWYG to some extent implies a particular layout, whereas docs can be generated from reST using a variety of styles and formats, so the same docs will look very different depending how it's processed. More common with reST are text editors with a preview pane feature, where you edit the source and see a rendered version generated alongside it, usually updated live with a short delay. Those often require the installation of additional software to process the source, though.

As you said, though, working in source code form actually frees you up from having to deal with formatting. In fact when writing reST docs it's best to ignore layout or formatting concerns. Formatting isn't decided until the docs are processed, and theoretically it can change at any time. We could end up deciding to switch to a different template for the HTML docs, or to start generating them other formats that don't use HTML at all. The focus with reST is on the content, not the presentation, and the content is definitely the most important thing.

And this github is apparently not as click-and upload as the bugtracker, but uses text commandos for every action. (However I have not yet found the command line in the web interface). It has been educational, but demotivating.

Ouch, well sorry to hear that! There's a pretty steep learning curve with Git, it's true.

As a collaborative version control system, Github isn't a simple click-to-upload file repository. You've no doubt gotten the basic rundown in those resources you mentioned, but if it all still sounds confusing, don't worry: It definitely is. Even those of us who've been using Git for years still occasionally get thrown by some aspect of how it works. I'd be worried if someone didn't find it confusing in the beginning.1

But like I said in the intro, you can worry about as much or as little of that as you're comfortable with. And as I said earlier, the content is the important thing. If you prefer not to deal with all of that and just want to upload images or provide new content in comments on this issue, that'd work for me. I can submit PRs with your changes and mark you as the author. (Git is designed to facilitate giving proper credit in pretty much any situation.)

Crap, this is already getting really long, so I'll stop here and respond to the specific items you raised in a separate comment.

Notes

  1. If you do want to delve into Git, it doesn't have to be a command-line-only experience by any means. There are a multitude of GUI tools built for managing local clones of Github repos, including (for Windows and Mac users) Github's own Github Desktop app. Github Desktop isn't an editor, it's purely a file manager that understands git repo structure and can communicate with remote repositories to synchronize changes. Many advanced text editors also have Git tools either built in or available as plugins, so that changes can be committed and pushed without leaving the editor.

    It's also possible to edit files directly in the Github web interface, and as you discovered there's no command line there, but that just shows that you don't absolutely need to get your hands that dirty. To edit a file via the web interface, you can just click the pencil icon in its upper-right corner (take docs/getting_started.rst for example). When you started editing, Github would see that you don't have permissions to make changes directly to files here, so it would set you up with a copy ("fork") under your account, where you can make changes before submitting them as a Pull Request.

    Editing on the web is perfectly workable, the only downside being that there's no real way to preview your changes. With a local clone you can use a previewing editor or (if you have the necessary Sphinx tools installed) generate updated HTML docs and view them in a web browser.

ferdnyc commented 4 years ago

Addressing some specific points:

What I have not found are the standards for the manual.

To the extent any exist, they're mostly implicit rather than explicit. The existing docs are the best guide to how the content should be produced. Beyond that, I'd say it's up to you. It'd be great if you wanted to formalize and document whatever standards you do apply, though, so others can follow your guidelines for future updates.

Most pictures are .jpg, are (animated) gif ok too? What compression level/file size do you want?

The current images notwithstanding, PNG would actually be the preferred format for screenshots, as it's not subject to compression artifacts the way JPG is. JPG is fine too, though, if the quality is high enough (I'd say 90% or better) — clarity is the priority, not file size.

I had to think about the animated GIF thing a bit. It's not out of the question, if used sparingly. But there are some issues with animated gifs, when it comes to documentation:

  1. The quality and/or file size ratio, which tends to be abysmal (and multi-megabyte GIFs can take forever to download and start animating)
  2. The animated component is only visible when the docs are viewed in web form

Since the manual should ideally be useful in print form as well, any animated elements should enhance the information presented in the static content, rather than replace it. Whatever happens in the animation should also be described in full detail in the accompanying text.

In fact, for supplementing the text content with more dynamic elements, rather than animated gifs we may just want to go straight to video. Embedded videos are not only clearer and higher quality, but they're click-to-play which avoids forcing a large initial download on the user.

After I saw your post, I went and put together a quick Sphinx extension so that we can embed YouTube videos into the documentation. It's in my PR #3394. Basically you just provide the ID or URL of the video, and it'll be embedded at that point in the docs.

Same concerns apply regarding viewability in print or other forms, of course. But certainly for something like a tutorial chapter, embedding an example of the final result would be a great use of the HTML format.

Most screenshots seem to be 4:3, are 16:9 screenshots ok too?

Images should be whatever shape they need to be in order to show the necessary information, there's no fixed aspect. But since images will be scaled to fit the width of the page, in general images shouldn't be unnecessarily wide or they can end up too small when displayed.

Many of our images are even taller than 4:3, in fact. A number are closer to square, and a couple (curve-presets.jpg and export-profiles.jpg) are even taller than they are wide. But then there's also transition-reverse.jpg, the second image in the Transitions section which has an aspect ratio of 4.69 (1258×268).

Though, if you look at transition-reverse.jpg in the document, it ends up being kind of small in a narrow browser. It's wider than it needs to be, and wastes a bunch of horizontal space. Ideally it would be sized without that empty Timeline space on the right.

You use green arrows and black numbers in circles to point things out. Do you have color numbers for them?

That green circle callout is actually in the repo, as docs/images/circle.svg. So, I can tell you from that file that the fill color is:

.style {
  color: #aec255ff;
}

And as far as using them in illustrations, the numeral in circle.svg (currently a "1") is editable in software that can edit SVG files (e.g. Inkscape, Illustrator). You'd also need the font ("Ubuntu") that's used for the numbers. Otherwise, if you provide a list of what numerals, sizes, etc. you need, I can generate a set of transparent PNGs for you.

Are there other requirements to keep in mind?

There probably are, but nothing comes to mind right now. Anything that comes up, just ask, I guess. There's very little in the way of hard requirements, really, since there hasn't been a lot of work done on the docs so far. The person who originally wrote a section is typically the only one who's touched it since. (Which isn't to say that anyone else shouldn't touch any part of the existing docs. Everything's on the table, as far as edits go.)

There are a lot of explanations and solutions available on the reddit help and here in the github tracker. Can any be re-used without asking or will everything have to be re-done? (Do you have a a license to everything uploading here, which of the users belong to the project and will agree to re-use of their screenshots and help?)

Any contributions to the actual repo (including docs) are licensed under the same GPLv3 license as the existing source. I wouldn't be surprised if that extends to anything posted in the Issues board, too, but even if that's the case we should ask permission before reusing anyone's content in the manual — especially images

Screenshots posted in Issues typically aren't ideally formatted for documentation anyway (due to the aspect/cropping issues I mentioned, etc.) and unless they were taken with the current version of OpenShot they may show an older version of the UI, which could be confusing. So it's usually best to make new screenshots for the documentation, sized and cropped to show just the relevant parts of the interface.

Whether someone's a contributor or not doesn't really matter, any content posted outside of the repo wouldn't be covered so same parameters apply. Even @jonoomph's content can't really be assumed to be part of OpenShot, unless it's something posted at https://openshot.org/ — but even then it's a good idea get his OK before including it in the documentation, really. If nothing else, simply because it's the polite thing to do.

ferdnyc commented 4 years ago

Most screenshots seem to be 4:3, are 16:9 screenshots ok too?

Images should be whatever shape they need to be in order to show the necessary information, there's no fixed aspect. But since images will be scaled to fit the width of the page, in general images shouldn't be unnecessarily wide or they can end up too small when displayed.

In fact, now that I've tested it I see that the page layout has a width cap that makes 696px the effective maximum width for images (at least in Chrome on my desktop). Anything wider than that gets scaled down, so you start to lose detail.

ferdnyc commented 4 years ago

You use green arrows and black numbers in circles to point things out. Do you have color numbers for them?

That green circle callout is actually in the repo

You may also notice a matching green arrow that's used on several of the screenshots, particularly in the Quick Tutorial section. That image... is not in the repo. (*sigh*)

So you'll need to use something else, if you need to point to anything. Feel free to replace both the circle and the arrow (along with any other clip art) with a new set, if you prefer. (Own work or images covered under an appropriate free license only, please. We'll need to include the license and source details in the repo, for any images covered under an open-source license.)

It doesn't have to match the existing design. A lot of those old screenshots should really be updated anyway.

MBB232 commented 4 years ago

I found a rest plugin for Notepad++ https://github.com/steenhulthin/reStructuredText_NPP

I also have more questions. One step ahead, two steps aside. :-) On the upside, i think you are basically writing a documentation howto in your answers.

Copyright notice: Why does it have an end date (or begin date for that matter), does the copyright expire after that end date? I thought it depended on the dead of the author - in this case the immortal openshot project. :-) Should they be updated to the current year? Can they be written dynamically so they automatically get updated to the current year? example here: https://raw.githubusercontent.com/OpenShot/openshot-qt/develop/doc/files.rst

License Documentation is sometimes covered by CreativeCommons licenses. But since you use yours interactively in Github and Sphinx, I guess it is better to keep the same as the rest of Openshot and stay with the same as the current documentation. (GPL 3 right?) So for what its worth, by this I give my permission to use all my comments, pictures and ideas given here and on the Reddit/openshot for openshot under that license. And for completeness, do you give it for your comments? (I think I can guess the answer).

Do you want to start a separate thread where all permissions for documentation are collected?

Tags Do you have tags for comments/topics with lengthy explanations that should be added to Documentation or FAQ? I noticed a tag 'workarounds' of which some should probably included?

Demo art in screenshots Some screenshots have demo clips and icons for art in them. https://github.com/OpenShot/openshot-qt/blob/develop/doc/images/quick-start-music.jpg Should these be the same in all screenshots to prevent confusion? Is there a zip with 'demo' art somewhere?

Images You say that the page layout has a width cap that makes 696px. You mean that that it is set somehwere in the framework, and not dependend on your screen size? Is this the same for the export to offline documentation, or does that use a different width?

Does github versioning keep copies of old images too or only of text? What is the preferred way to include replace images; rename the old one to _old and include a new one with a new name? Or add the new file with a new name, and update the link in the source code?

I propose that images should include the name of the page they appear in. Unless they are used in multiple pages?

syntax Browsing through the existing files I have found some syntax, that should be sufficient for most basic actions. I have not found how to include a hyperlink to text. Is there an equivalent to <a href="" ?

*   cursive?
**  Bold

..  hide lines
=== underline with this to make a headline
------------    or underline with this for sub-headline

.. table::
   :widths: 5 20
hidden line to define table of minimum cell width of 5  pixels  for first column, 20 for second column, undefined for those after
use ====================  ============ to start and end the table, with 2 spaces to separate comlumns
? (column 1 is not showing in Github)

.. image:: images/quick-start-drop-files.jpg 
    hide line +add image
MBB232 commented 4 years ago

I'm using online github for now. I could not find a fork button on the documents-dir, so I was afraid that I would have add the files one by one. So I started with one file and used the edit-button, and it created my own file like you said it would. It forked the entire project ! :oops: It seems to have also lost the actual change I made (update the copyright year to 2020 in Profiles.rst) Apparently I need to click on "MBB232 Update profiles.rst" on top left after committing even in my own fork?

Not quite sure how to send only that file back to to you. There is a 'new pull request' under "pool requests 0", but I am not sure how that allows me to select particular files. (It also lists multiple projects?) Why is it called a pull request when I want to send a file to you, shouldn't that be push, as in 'push away from me'?

reST is becoming more clear, it seems fairly straight forward once you have a starting point.

There is an open issue where you created more custom tags for hotkeys, but they do not seem implemented?

https://github.com/OpenShot/openshot-qt/issues/1354

Has there been a change of mind, or is this on the todo--list? (seems like a fairly easy to change in the documentation for me to get started, but considering your screenshot you already implemented it somewhere. https://user-images.githubusercontent.com/538020/37234871-54fe5d7e-23c8-11e8-9606-01dd2d59ba0e.png

I started to make some changes to better explain profiles, as I already ran into that myself and on the ask-reddit https://github.com/MBB232/openshot-qt/blob/develop/doc/profiles.rst The lines I do not figure out are sample_aspect_num=1 sample_aspect_den=1 a quick google let me to.... the MLT framework that it originates from :-D https://www.mltframework.org/docs/profiles/ Apparently it has something to do with aspect ration. However, they do use values different then 1 for them. Does openshot use then as relative to display ration, and thus always expect 1:1 ?

befocken commented 4 years ago

syntax Browsing through the existing files I have found some syntax, that should be sufficient for most basic actions. I have not found how to include a hyperlink to text. Is there an equivalent to <a href="" ?

* cursive?
**    Bold

..    hide lines
===   underline with this to make a headline
------------  or underline with this for sub-headline

.. table::
   :widths: 5 20
hidden line to define table of minimum cell width of 5  pixels  for first column, 20 for second column, undefined for those after
use ====================  ============ to start and end the table, with 2 spaces to separate comlumns
? (column 1 is not showing in Github)

.. image:: images/quick-start-drop-files.jpg 
  hide line +add image

I can recommend this repo, where you can see all the different syntax of markdown :)

ferdnyc commented 4 years ago

@befocken The documentation isn't written in Markdown, it's reStructuredText (.rst)

befocken commented 4 years ago

@befocken The documentation isn't written in Markdown, it's reStructuredText (.rst)

Well I was mislead then :D

ferdnyc commented 4 years ago

Returning to some older items:

Copyright & Licensing

Copyright notice: Why does it have an end date (or begin date for that matter)

You can think of that as meaning "contains content copyrighted between (start) and (end), meaning various revisions to the content may have been made during any of those years.

Should they be updated to the current year? Can they be written dynamically so they automatically get updated to the current year?

In fact they shouldn't, it turns out. In the past we've done sweeping updates to the date ranges, but better minds have detailed why that's a bad idea:

Updating the copyrights

I have noticed some developers “updating the copyrights” on works which have not changed in a given year. Do not do that. A copyright notice tells someone when a work was published. If you did not change the work, there is no reason to keep changing the dates.

If a file is edited, its individual copyright statement can then be updated to include the current year. It doesn't need to be, though; copyright (at least in the US) is automatic and requires no explicit notice. Plus, the copyright statement for the project as a whole is generally (or, at least, is more likely to be) updated with a date range up to and including the current year, which can theoretically be taken as applying to all of the component files included in the source distribution.

Content license

Documentation is sometimes covered by CreativeCommons licenses. But since you use yours interactively in Github and Sphinx, I guess it is better to keep the same as the rest of Openshot and stay with the same as the current documentation. (GPL 3 right?)

Yeah, and more critically the documentation source files are included in the repo, so if they were licensed differently we'd have yet another license covering certain parts of the source code (there are already some icons, fonts, etc. re-used from other projects under their own licenses), which is just unnecessary additional hassle.

There is a GNU Free Document License, but it's not compatible with GPLv3 (ironically) and has fallen somewhat out of favor in recent years, so there don't appear to be any real advantages to it, vs. just sticking with the GPL.

Content rights/permissions re-re-redux

So for what its worth, by this I give my permission to use all my comments, pictures and ideas given here and on the Reddit/openshot for openshot under that license. And for completeness, do you give it for your comments? (I think I can guess the answer).

I've been reluctant to give an answer to that, not because I'd object to my posts being used in the documentation, but more because I'm having trouble imagining a scenario where any of my posts would be useful for the documentation.

I guess my take on the user guide is that it's a document with a specific purpose: Instructing the user on OpenShot's features, functionality, and UI, so that they're aware of what it's capable of and how they can use it effectively. IOW, (in my head, at least) it's a concise, focused document in exactly the way my posts are not.

And, I should maybe clarify: When I said we should get permission before using anyone's content for the documentation, I meant using it directly. All of the Issues and etc. are absolutely fair game to use as reference, in fact that's largely the point of the docs tag in Issues — to flag reports where part of the outcome was, "We should really cover this in the manual", or "we should really write better documentation about this feature". But the intention there was just that — to write documentation covering it, using those issues for reference / guidance.

Unless we're literally copy-pasting someone's Issues comments text into the documentation wholesale, there's no need to worry about getting permission from them. And if any of my comments are suitable to be copy-pasted into the documentation, without requiring a complete rewrite... well, I think I'd like to know about it, on an individual basis. I mean, it's not every day you see a unicorn!

So, I guess the short answer (hah!) is: No, I don't think it's wise to offer blanket permission to use my content for the manual. Beyond what I write and submit directly in PR form, if any of my contributions are going to be used I'd rather be asked first. Mostly so I can try to talk people out of it, for the sake of the document's ultimate readability. :wink:

FAQs and tags

Tags Do you have tags for comments/topics with lengthy explanations that should be added to Documentation or FAQ?

Ah, see, now a FAQ is a very different thing. I think maintaining some sort of FAQ is probably a worthwhile effort, though such things unfortunately tend to get outdated quickly, and often end up starved for the resources (person-resources, time and effort) necessary to maintain them. Still, if we can manage it that'd be great.

Partly for the sake of recency and timeliness, I don't think the FAQ should be part of the User Guide, though. They have very different purposes. The FAQ should probably live on the project wiki where it's directly editable by anyone if they have information on a topic that's not yet addressed. The User Guide can certainly link to the FAQ page/pages, either in a "Further Resources" type section, or maybe even inline when relevant features are documented.

And, in fact, looking at the page list now there are several FAQ-like pages already there, most of them no longer very current. (Oh, and hey, turns out it was a wiki page that mentioned the documentation only being available in English! Knew I saw that somewhere.)

Regardless:

Workarounds

I noticed a tag 'workarounds' of which some should probably included?

Perhaps in a FAQ entry, if they're still relevant, yeah. Only in very rare cases would there be a workaround that's useful and long-standing enough to warrant mention in the formal documentation. Though now that I'm thinking about it, there are probably a few. Most likely they'd be in older issues that don't have the tag assigned, though.

The tags in general are relatively recent additions to the Issues board, and most of the "workaround" tags in particular will be out-of-date. That typically gets assigned when there's a bug report for which a workaround is found that can serve until it gets fixed — but when a fix is released, we don't remove that tag or anything. Issues that have a workaround are more likely to have been addressed "for real", since if there's a workaround it'll often provide guidance as to how the problem can be addressed.

(Take #3408, for example — which I didn't even bother tagging, because the PR was already submitted with the actual fix. We knew pretty much from the start that the issue only occurred when Blender was used with directory names containing non-ASCII characters. The workaround was simple: Just make sure not to do that. Simple enough, just stick to simple file/path names for now. But the specific nature of the problem also made it easy to find, and it was addressed within just a few days of being reported. That fix has already been merged into the development code, so there's no longer any need for a workaround.)

Image content

Demo art in screenshots Some screenshots have demo clips and icons for art in them. https://github.com/OpenShot/openshot-qt/blob/develop/doc/images/quick-start-music.jpg Should these be the same in all screenshots to prevent confusion? Is there a zip with 'demo' art somewhere?

There isn't, and I don't think it's a huge concern... in fact, part of me thinks that it's a good thing if the screenshots show different content, since it's an opportunity to illustrate the variety of different features and configurations available.

That being said, for certain parts of the documentation, say during a step-by-step tutorial for some feature or whatever, it may make sense to have a set of consistent imports for all of the steps, so that the illustrations reflect exactly what the user would expect to see in the actual software.

In fact, it could even be cool to put together some sort of "tutorial project" — like, say, a ZIP file with one or more tutorial.osp files, plus whatever media files they reference — so that the user can download that and load the project into OpenShot locally, if they want to follow along with the tutorial steps.

But that's getting way ahead of where we're at right now. And other than those instances where it would be instructive to have a set of related/connected images show progressive interactions with the same media files, I don't think it's necessary to use common input data for all of the images. In fact, I feel there's probably value in not doing that.

Formatting/sizing

Images You say that the page layout has a width cap that makes 696px. You mean that that it is set somehwere in the framework, and not dependend on your screen size? Is this the same for the export to offline documentation, or does that use a different width?

No idea. I'd guess that it varies from device to device, browser, OS, screen size, etc., but I couldn't say how exactly.

All I can tell you is that I have a full-HD[-plus-a-little-extra-height] 24" screen, but when I have a Chrome window open with the manual loaded into it, once the window hits about 1160px wide, that's it — the content stops getting any wider. Past that width (which is including the sidebar), the only thing that grows is the empty space to the right of the content container. And at that size, the images are scaled to 696px wide.

I'm sure it's different for print (though that's a distant, minor concern, compared to the online presentation), and I'm sure it's different for mobile readers and readers with HiDPI laptop or standalone displays. But regardless, clearly using any fullscreen HD screenshots or whatever shouldn't even be considered, unless maybe it's to capture extra detail on a scaled display. Because images that size can end up scaled down to a third of their width or smaller, and at that size all of the UI elements will be impossibly tiny unless they started out scaled up in the original image.

When I take screenshots to post on GitHub or in the docs, I usually resize the OpenShot window down to about a quarter of my screen. Or at least, no more than half of the width — if I need some extra height for a long menu or whatever, that's not such a problem, in fact as we've discussed narrower-aspect or even portrait images are in some ways a better fit for the manual layout.

In general, though, I'd say that even 1280x720 is a bit too big for user guide images, if the interface is unscaled. Preferable to keep the width under 1000px. That way, the images shouldn't end up getting scaled down much more than ~50%, and hopefully they won't lose too much detail.

Version control

Does github versioning keep copies of old images too or only of text?

Absolutely everything is versioned in git, including any type of binary data — whether it's able to interpret the file or not. (People can and do version encrypted data, even.) In fact, Github will even display differences between binary file revisions, for certain file formats (images, mostly).

For example, here's a commit from an old PR where I made adjustments to the application icon, just to tweak the framing so its dimensions were square:

https://github.com/OpenShot/openshot-qt/pull/2060/files?short_path=507f2e1#diff-507f2e160620bca2579b3a6a48ec1982

If you click the "sheet of paper" icon in the upper right of either file's toolbar, it'll switch to a visual comparison mode, there are a few different ways you can examine the differences between the two versions.

File naming

What is the preferred way to include replace images; rename the old one to _old and include a new one with a new name? Or add the new file with a new name, and update the link in the source code?

If a new file is a replacement for the previous one, and the name of the old file makes sense, I'd say just overwrite the old one. It's simpler, less cluttered, and the previous versions are all in the repo history if we ever need to retrieve them.

If the name is nonsense or has no relationship to the content, feel free to give the new file a different name and change the content reference. Don't go creating new versions of "Screenshot 2013-12-13.jpg" — Or worse, creating a new version named Screenshot 2013-12-13.png). That'd be borderline sociopathic. :laughing:

Poor choices in file naming, or anything else, should be interpreted as non-choices ­— assume that if a name makes no sense or is actively misleading, it's because the name happened completely at random, for all intents and purposes, and nobody noticed or cared. It's a good bet that no thought whatsoever went into the original naming, and not at all likely that someone made a conscious decision to give it a stupid name. Nor should you worry that someone might be attached to that stupid name.

To bastardize a cliche, a good rule of thumb here is, "Never attribute to malice what can adequately be explained by complete inattention."

I propose that images should include the name of the page they appear in. Unless they are used in multiple pages?

Hmm, that's an option, if it works for you then cool. I'd somewhat discourage that unless it were reasonably certain that page names aren't going to change, but I don't think that's a very good bet. So, my worry is that as the manual organization evolves and titles are rethought, page names might change, and images might get shuffled between pages. We certainly shouldn't be renaming our images to follow our page renames, that's just tedious, but having images named for the wrong pages or pages that no longer exist could be confusing.

My personal take would be, images should be named descriptively. It should say what it is, and it should be what it says. Names like intro-tutorial-step-1.png (followed by -step-2.png through -step-n.png), export-interface-simple.png, and so on seem to me like they'd have the most staying power and relevance long-term.

But, having made my case there, I really don't care very much, and certainly have no interest in trying to dictate how you organize your information. Ultimately a file's name is completely irrelevant as long as it has one, so really I'm perfectly content to go with whatever you decide.

(Though I admit I may feel compelled to foment dissent among the unwashed masses, eventually urging them to rise up and overthrow their oppressors, if I see any newly-created files named Screenshot 2013-blahblah.png or whatever.)

MBB232 commented 4 years ago

And if any of my comments are suitable to be copy-pasted into the documentation, without requiring a complete rewrite... well, I think I'd like to know about it, on an individual basis. I mean, it's not every day you see a unicorn!

As I said before, you are basically writing the essence of the howto by explaining it to me. I have been copy-pasting parts for my own use. And reworking it for general use by combining parts, stripping out loose lines and adding my own discoveries. And then reformatting for the shorter lines as you advised. For example, I like the way you described the purpose of the manual. Then the above paragraph could become:

The user guide is a document with a specific purpose: Instructing the user on OpenShot's features, functionality, and UI. So that they are aware of what it is capable of and how they can use it effectively. It is intended to be a concise, focused document.

(Maybe swap the third and fourth line to get a better flow)

By now I think I have a pretty complete document, though it will need revising. If you would take a look? (Notes are hidden in the RAW format) Be prepared to see a herd of unicorns!

Unfortunately, my rst file is not read as a Rest file by Github to layout like those from Openshot, but stays plain text. So I can not check the result. Does the filetype need to be set in Github somewhere? The odd thing is that when I copy text directly from openshot files they are seen as Rest files.

https://github.com/MBB232/openshot-qt/blob/MBB232-AboutDoc/doc/AboutDoc/Documentation_About.rst

I also converted the copyright license to the one-sentence-per-line format. PS: While it may be useful to update the header (and other hidden lines) for versioning (as you explained), they will not be processed by Sphinx because they are hidden. So putting everything on a new line will not see them automatically combined because they are only visible in raw text.

MBB232 commented 4 years ago

List of issues/questions that maybe could be added to documentation

Set custom Bitrate/Quality as default #3381 https://github.com/OpenShot/openshot-qt/issues/3381 Under Files, In&Export or Profiles?

ferdnyc commented 4 years ago

About to finally poke my head in at https://github.com/MBB232/openshot-qt/blob/MBB232-AboutDoc/ and have a looksee.

(Er... after I make some dinner. Yes, I am on the east coast of the US and it is just shy of 7am here. Yes, I mean dinner, not breakfast. What, can't a person be 12 hours late for dinner? I always have dinner when I read Github, everybody knows that!\</DarkHelmet>)

Aaanyway, assuming I can pull together 20 minutes of focus and finally do get around to preparing my 12-hours-late "evening" "meal", I'll be able to take a look. Sorry it's taken so long.

(Edit: "Forgot" the "scare quotes". #ForGreatSarcasm!)

(Edit2: Obligatory link to the "blog" of "unnecessary" quotation marks.)

MBB232 commented 4 years ago

A familiar situation. Here I was sometimes posting in the middle of my night (western Europe) so you Americans would be awake. (At least, that was my excuse. Now There goes that :-) )

Under while, I am working on a version of ABoutDoc that gets recognized, and practize my Rest. https://github.com/MBB232/openshot-qt/blob/MBB232-AboutDoc/doc/AboutDoc/files.rst To get it working, I had to re-upload an existing project file and edit the content. Do you understand why files I create are not seen as Rest, and project files are? (IF you download the first linked version of AboutDoc, is it seen as a real Rest file in your local Rest reader?) PS: Turns out, some bad syntax breaks .rst from working in Github. Like starling a line with spaces before the ====== underline symbol

I also finally discovered the important difference between ` (left from 1) and ' (left to Enter). That it toke me an hour to figure out issues like that is probably the main reason that Programming does not appeal to me.

ferdnyc commented 4 years ago

I also finally discovered the important difference between ` (left from 1) and ' (left to Enter). That it toke me an hour to figure out issues like that is probably the main reason that Programming does not appeal to me.

Hah! Yeah, that one's pretty good, coders do love their many, many particular little symbols.

Doesn't even come close to rivaling the amount of strife and anguish sowed by the whole "backslash vs. forward-slash" thing, of course. Stroke of genius, that one.

Now, whoever decided to embrace (three) [different] {styles} of enclosing brace-pairs (four if you count \<tag> format, thanks HTML/XML), with a completely different meaning assigned to each one... well, TBH I kind of feel like that was just greedy and/or cruel.

(Hah, it's funny because we are terrible, terrible people!)

Of course, it only gets really complicated once you bring our friends the ‘smart’ “quotes” into it, AKA "typographic" quotes, which ironically can't actually be typed directly on standard keyboards, so you have to rely on editing-software automated replacement features to apply those. (Hence the "smart" in "smart quotes", which I have to assume was meant ironically because all software is extremely stupid, and literal to a fault. If sometimes so convoluted that it can appear to be performing some sort of artistic interpretation of the user's instructions more than actually following them.)

Case in point:

Do you understand why files I create are not seen as Rest, and project files are? (IF you download the first linked version of AboutDoc, is it seen as a real Rest file in your local Rest reader?)

You're referring todoc/AboutDoc/Documentation_About.rst right? I don't even need to download it, I can confirm that it's not recognized as ReStructuredText because Github's web interface displays it as plaintext. If it were identified as ReST there'd be a "rich" (rendered) view, like there is for files.rst.

The reason Documentation_About.rst isn't recognized as ReStructuredText is because it's not, technically. There are parsing errors that make it illegal ReST markup, so therefore it's not ReStructuredText. (This goes back, in part, to the whole issue of ambiguity in ReST's syntax definition. Since ReST was invented as a way of embedding documentation into Python code, the file extension is meaningless — most ReST content would be found inside .py files, not .rst files — so naming a file something.rst doesn't make it ReST. It's ReST if it's named something.rst and the parser is able to parse it as valid ReST without encountering any fatal errors.)

The best way to find errors is to run the file through Sphinx, which will report the location of every parser issue it encounters. Short of that, the syntax highlighting can provide clues as to what's wrong. For example, though it wouldn't be a fatal error, the first syntax errors in the file are here: https://github.com/MBB232/openshot-qt/blob/a87fc2fc66f47c1de57eabf2f459bd9ad85086e3/doc/AboutDoc/Documentation_About.rst#L18-L20

The highlighting changes from gray to black because the following lines aren't indented at least one space, so they fall out of the comment block and become body text.

Beyond that, it contains a bunch of :: comments that should be .. comments.

Also, these QUESTIONs are colored black instead of gray because they're invalid syntax, specifically explicit markup not followed by a blank line. https://github.com/MBB232/openshot-qt/blob/3890e847f0719605939188aa0bc7618df73b1d91/doc/AboutDoc/Documentation_About.rst#L193-L201

Like I said, the best way to validate is to run the file through Sphinx. To that end, I set up a basic environment for doing so in the AboutDoc directory, and the PR I just filed to your fork is a request to add those changes to the MBB232-AboutDoc branch.

ferdnyc commented 4 years ago

And, once again FeRD forgets that you can't embed file references across repos on Github. For no obvious reason, other than "they enjoy seeing people repeatedly screw that up time and time and time again", perhaps?

ferdnyc commented 4 years ago

Anyway, having performed the make dummy that will just cause Sphinx to perform a syntax check on the files in the directory, here's the output, run through fmt -s to wrap the long lines:

/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/Documentation_About.rst:19:
WARNING: Explicit markup ends without a blank line; unexpected unindent.
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/Documentation_About.rst:131:
WARNING: Unexpected section title or transition.

==================
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/Documentation_About.rst:132:
WARNING: Definition list ends without a blank line; unexpected unindent.
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/Documentation_About.rst:135:
WARNING: Unexpected section title or transition.

-----------------
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/Documentation_About.rst:136:
WARNING: Definition list ends without a blank line; unexpected unindent.
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/Documentation_About.rst:137:
WARNING: Line block ends without a blank line.
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/Documentation_About.rst:185:
WARNING: Explicit markup ends without a blank line; unexpected unindent.
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/Documentation_About.rst:235:
WARNING: Title underline too short.

Tables (to-do)
------
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/Documentation_About.rst:235:
WARNING: Title underline too short.

Tables (to-do)
------
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/files.rst:20:
WARNING: duplicate label documentation_ref, other instance in
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/Documentation_About.rst
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/files.rst:170:
WARNING: image file not readable: images/quick-start-drop-files.jpg
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/files.rst:177:
WARNING: image file not readable: images/file-menu.jpg
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/files.rst:200:
WARNING: image file not readable: images/file-split-dialog.jpg
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/files.rst:220:
WARNING: image file not readable: images/file-add-to-timeline.jpg
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/files.rst:242:
WARNING: image file not readable: images/file-properties.jpg
looking for now-outdated files... none found
pickling environment... done
checking consistency...
/home/ferd/rpmbuild/REPOS/openshot-qt/worktree-MBB232/doc/AboutDoc/Template.rst:
WARNING: document isn't included in any toctree
done
ferdnyc commented 4 years ago

Oh, hey that's nice. Turns out running make dummy in the root doc/ directory wili include the contents of AboutDoc automatically. Unexpected. Still, though, those files won't be included in the TOC (I have to make sure they're not included in the final documentation build, come to think of it, or we'll have to move them or exclude them explicitly from the build), plus it's nice to be able to generate just the contents of that directory independent of the main OpenShot documentation.

The root doc/ directory Sphinx run also hits a bunch of errors in AboutDoc/files.rst because it contains relative image paths, and those become invalid when the file is moved. Another reason it's definitely better to modify files in-place, then you don't have to deal with updating all of the references.

(I realize files.rst in AboutDoc wasn't copied for the purposes of updating it as a new version of files.rst, so that's not really applicable in that case. But it does illustrate the advantages of in-place updates to existing content, with the modifications tracked and contained using git's branching features, rather than on-filesystem duplication.)

ferdnyc commented 4 years ago

FNARD. AboutDoc is included in the OpenShot User Guide documentation build automatically. Stupid overachieving Sphinx! Still, I'm sure the directory can be excluded without too much trouble.

(Edit: Yup. Commit added to my PR in your fork, turning off AboutDoc inclusion in the make html (and friends) build for the project /doc/ directory. So, now AboutDoc/Makefile is necessary to run Sphinx on those docs.)

ferdnyc commented 4 years ago

Sphinx's own documentation can be a good source of inspiration / hints regarding ReST syntax and features, since of course it's all written in ReST and the source of every page can be viewed in their GitHub repo.

But even their formatted docs are helpful. For example, this page reminded me that:

MBB232 commented 4 years ago

I can confirm that it's not recognized as ReStructuredText because Github's web interface displays it as plaintext. If it were identified as ReST there'd be a "rich" (rendered) view, like there is for files.rst. That's what I noticed, hence my question. I thought it may be an ascii/ANSI thing or a file permission or something. You are right of course, it was bad syntax. In this case the line:

Titles are underlined

By cut-pasting in one paragraph at the time, I found this was what it broke on. (And a bunch of other things that acted weird)

The reason Documentation_About.rst isn't recognized as ReStructuredText is because it's not, technically. There are parsing errors that make it illegal ReST markup, so therefore it's not ReStructuredText. ... It's ReST if it's named something.rst and the parser is able to parse it as valid ReST without encountering any fatal errors.)

Rest being what you explained it was, I was expecting it to be less sensitive then HTML, not more. And that was why I was NOT expecting a few mistakes to be such an issue. I thought it would just skip the broken things and continue parsing afterwards. (And either render that line plain or as headline, not to make the file illegal). Anyway, it is working now.

Beyond that, it contains a bunch of :: comments that should be .. comments.

Yes, you pointed that out before, they are on my to-fix list. I initially mixed them up because Rest uses them both in .. image :: It seemed logical because I must have vaguely recalled that :: can used to comment stuff out in Batch files. 🤔 I'll work my way through your full error list.

Also, these QUESTIONs are colored black instead of gray because they're invalid syntax, specifically explicit markup not followed by a blank line.

They are not supposed to be syntax at all They were supposed to be commented out plain text lines 😢 Hiding hyperlinks after them seems to work if there are some normal words in between.

Like I said, the best way to validate is to run the file through Sphinx.

I was hoping to avoid that . May give it a try on my Ubunty VM coming week, but it is quickly growing way beyond the initial scope of offering a few quick missing tips to the docs. 😢 Maybe it's time I finish my first video project first. (And I've seen advice thrown around that maybe Windows users with Nvidia cards should be looking around for other software alltogether)

To that end, I set up a basic environment for doing so in the AboutDoc directory, and the PR I just filed to your fork is a request to add those changes to the MBB232-AboutDoc branch.

Uh, Thanks? I have no idea what that means. Or what that does - Are you telling me that github will run /code/ hosted on Github to parse other code hosted in the same github? That's creepy cool. (And how am I sure you did not just offer me code to run a bitcoin miner on my github account? 😜 )

MBB232 commented 4 years ago

Still, though, those files won't be included in the TOC

Well, they really /should not/, it is just meta-documentation for beginners that want to help at the documentation. No reason to bother people that want to use the software with it.

The main reason I was writing them in Rest because the rest 😊 of the documentation was written that way. I wanted to stay in the same format, and store it close. Also I thought it would be a good practice writing in Rest. (And I did not know you had a wiki. I realize now, I could have been writing in LO Writer! 😒 ) Nevertheless it is really paying off bonus dividend in the practice, it has been 'educational' in what does (not) work.

Spaces are verboten in image filenames, so it's dashed-multi-word or CamelCase for those. (Probably a good rule for .rst filenames as well, whether or not it's an actual requirement.)

Glad my stumbling in the dark let you hit on something important. We should probably include that in the "File naming and directory structure"

I noticed that documentation filenames are connected with underscore _ but images are connected with dash - Neither uses the Upper/Under case. (CamelCase? Really? 🤣 ) Is there technical preference for either, or just a grown habit? Probably good to keep as-is, unless there is a reason not to. (Just to make sure, are there differences in code between the dash hyphen and minus signs? Are different key combinations needed to include them like the apostrophes?)

Image references can be written as "globs" rather than using an explicit extension, e.g. .. image:: some-image-filename.* Referencing the image in that way tells Sphinx to choose whatever format it prefers from the available matches, and it may even prefer a different format depending on the context.

Very cool from a technical perspective, but a nightmare in making for maintenance. If the PNG's were to be updated but not the JPG's, then different browsers/platforms/etc would show different versions of screenshots. And users filing bug reports may see different things in the same version number of the manual. Try troubleshooting that. I recommend not to do that.

It would be a way to solve your GIF loading issue. But a better way would be if images were clickable to load an animated picture. BTW, did you know animated PNG exists now too? Can Openshot export to that? https://litmus.com/blog/animated-pngs-in-email-an-alternative-to-gifs

Speaking of filenames, I forgot to address this

If the name is nonsense or has no relationship to the content, feel free to give the new file a different name and change the content reference. Don't go creating new versions of "Screenshot 2013-12-13.jpg" — Or worse, creating a new version named Screenshot 2013-12-13.png). That'd be borderline sociopathic. 😆

Clearly. The only way to go is the European date convention of DD-MM-YYYY.JPG. Still, could be worse; there are people that use MM-DD-YYYY! 😂

MBB232 commented 4 years ago

Also we both managed to fill several pages on the technical side, but what about the content? Do you think it will be useful? Do you feel comfortable to let your lessons be re-used that way now? Is the structure ok, or should technical and content documentation be split out over different files? Am I making glaring mistakes or are significant subjects missing? Do I need to run the whole thing through a spellcheck again?

Other then fixing the syntax, is it near ready to offer it for a pull/review request?

One subject missing is what you addressed in the other topic https://github.com/OpenShot/openshot-qt/issues/3427

Documenting the parts that don't work right, or at all However, due to the various unresolved issues around profile handling, in certain circumstaces the output encoding may not be a perfect match even with a profile that specifies the exact same parameters. Which leads us to (IMHO) the trickiest questions you'll face when writing documentation for OpenShot, for which I have no good answers: How, or do, you document the bugs? Should missing features be addressed, and in what way?

If the options are exposed in the interface, but NOT working in the software, it raises false expectations about what the software can do. People that spent time on a project expecting to use this feature, and then more time trying to find out why it won't work for them before coming upon a bug report would probably leave with a bad experience, and give it bad reviews.

So I think it is important to addressed in the documentation if things are broken/not intended to work. At least it will prevent users from wasting time on it, and at best it may lure in new programmers that want to include the feature. So probably a link to a bug report/enhancement request should be included? But it should not be given too much words to distract first-time users.

ferdnyc commented 4 years ago

Like I said, the best way to validate is to run the file through Sphinx.

I was hoping to avoid that . May give it a try on my Ubunty VM coming week, but it is quickly growing way beyond the initial scope of offering a few quick missing tips to the docs.

I mean, far be it from me to stand in the way of our masochism, but unless you simply enjoy pain there's no reason to bother with all of that. I was just referring to building them... you're on Windows, right? Python runs on Windows. There's no reason all of the docs build tools couldn't be installed. Or...

To that end, I set up a basic environment for doing so in the AboutDoc directory, and the PR I just filed to your fork is a request to add those changes to the MBB232-AboutDoc branch.

Uh, Thanks? I have no idea what that means. Or what that does - Are you telling me that github will run /code/ hosted on Github to parse other code hosted in the same github? That's creepy cool. (And how am I sure you did not just offer me code to run a bitcoin miner on my github account? )

Oh, heck, I wasn't even thinking of anything like that. Like I said, I just meant building them under Windows, but there's no reason that they couldn't just be generated by Github. That's the whole point of Actions. So, presenting PR MBB232/openshot-qt#3 — a full Github Actions config to automatically generate HTML from both doc/AboutDoc/ and doc/ itself, and post the results as downloadable ZIP files.

You should, I think, be able to see the results of it in action at https://github.com/ferdnyc/openshot-qt/actions/runs/96085356

ferdnyc commented 4 years ago

In fact, the Github Actions workflow is useful enough in general that I just installed it (for the doc/ directory) in the project repo

MBB232 commented 4 years ago

It looks pretty awesome, i'm starting to understand why all software projects have been moving to Github the last few years. (Lets hope it does not go down like others) I can't find the button to start the run, but it did somehow create the files. As it spews out the errors, does that mean it can also list the 'notes/questions/TODO' I added in the files as a list? (probably not worth it, but I'm curious) - Would creating bad syntax be a way to have it list todo- comments for the next person who wants to work on the docs?

ferdnyc commented 4 years ago

@MBB232 Yeah, Actions are automated so you can't start them manually. (There may be a type you can, but generally not.) To trigger a run, you check in commits. As configured, the job will run automatically for every pull request opened and every commit pushed.

As it spews out the errors, does that mean it can also list the 'notes/questions/TODO' I added in the files as a list? (probably not worth it, but I'm curious) - Would creating bad syntax be a way to have it list todo- comments for the next person who wants to work on the docs?

I had to think about that for a second. Task outputs are "annotations", which theoretically could mean anything (even non-error conditions), however the task isn't parsing the content, only the output from sphinx, so in part it comes down to what Sphinx could do.

Actually... taking a step back, you probably wouldn't want to do that anyway. Generating the docs is a process that (especially as it becomes more automated) isn't really intended for human consumption, so any communication during that process won't reach its intended audience.

IOW, ideally no person ever has to even read the output of the Actions runs. They just see a green check mark that means "no issues" and therefore no reason to investigate. Someone might be curious and take a look at the output once or twice, but that appeal fades quickly. The assumption is that most automated jobs will toil away in obscurity, their output never to be seen by human eyes.

So if there's non-error output that still results in the green check mark, nobody will ever see it. OTOH, if there's "notes" output that presents as warning/error conditions, then the automated tools can no longer determine whether the job executed successfully or not, so somebody will HAVE to look at it. (Which is a burden, especially considering the frequency of the runs.)

A "TODO" item is important for humans when editing the content, but irrelevant to machines when processing it.

ferdnyc commented 4 years ago

As configured, the job will run automatically for every pull request opened and every commit pushed.

That can be adjusted so jobs spend less time spinning their wheels, especially if updates are frequent. Typically actions are configured on "central" repos where updates are consolidated in batches via pull request, not development repos that see frequent changes.

In the case of our personal forks, though... well, I edit offline and typically don't push changes to Github until I'm ready to open a PR (or updating an existing one), meaning https://github.com/ferdnyc/openshot-qt still sees pretty infrequent changes.

If you edit directly on Github or push most changes to the repo immediately, though, that'd cause a lot of churn. The simplest solution there is probably to configure the workflow so that it only watches certain branches. You can make edits to "working" branches, and then merge that branch into the monitored branch whenever you want to generate updated docs. (Merging branch A to branch B doesn't change anything about branch A, only branch B. Even after a merge, you can switch back to A and continue making changes, merging to B periodically as a sort of "checkpoint". The history of A will contain only what's committed there. ...As will the history of B, up to each of the points A is merged into it.)

ferdnyc commented 4 years ago

Also we both managed to fill several pages on the technical side, but what about the content?

Yeah, I've been wanting to circle back around to that. And in fact, I'm skipping over addressing a lot of things here, because while meta-topics are interesting, I don't want to let myself (continue to) focus on those over the actual documentation.

Devoting some time to process initially is a necessary evil with Github and the like, though, because without those nailed down keeping track of the "real" tasks can be impossible. For instance, I had forgotten how difficult Github makes discussing code or giving feedback other than via the pull request system. I can see all of your MBB232-AboutDoc branch, I can even compare it to the openshot-qt:develop branch... but I can't offer any feedback on specific lines within the files. I'd have to go and find the individual commit(s) where that line was added and/or changed, to leave a comment.

When a pull request is submitted, all of the changes it comprises are consolidated so that they're easily reviewable, and comments can be attached to specific lines of code/content so that there's context for everything. Individual items can also be marked "Resolved" when they're addressed, which helps organize what needs to be done vs. what's taken care of.

I can give general feedback, of course, and I will: I think this is great. A lot of the information was "around", but scattered in different places where it's easy to lose track of. Getting it organized in one place and "formalized", I guess is one way to put it, should be a huge help for anyone needing to make changes to the documentation in the future. So, thanks again for taking the time on that.

I have some comments on certain specific things, but like I said that's best done in the PR context. I'd say, absolutely, let's get the meta stuff (the doc/AboutDoc/ parts) into a PR in the project repo, that way people have the option to start looking it over and generating feedback. And once that process has gotten started, let's move on to the actual documentation.

ferdnyc commented 4 years ago

If the options are exposed in the interface, but NOT working in the software, it raises false expectations about what the software can do.

Agreed without reservation, on that point. Ideally, broken things wouldn't be exposed in the interface, because if they're broken they shouldn't be there at all. But where they are, they need some caution tape wrapped around them to alert unsuspecting users.

Those are the easy ones, though. A bigger concern, and perhaps even one that comes up more frequently, is when something isn't exposed in the interface (typically because it doesn't exist and/or work), but someone expects to find it anyway. Whether it's through experience with other, similar software, notions of what things are "required" features for the class of software, a conceptual bias on their part regarding "obvious" feature needs, or what have you, they've got it in their head that something should be there that simply is not.

Specific example: We regularly have people asking how they can disable all of the clips on a particular track in the timeline, because they can't find that option in the interface.

It's true, they can't find it, because that option doesn't exist. You can't do that in OpenShot. It sucks and it'd be great if you could, and it looks like there may be attempts to address that, but it's a deceptively complicated feature to provide for various internal reasons, and at least for the moment it's not possible.

But it feels weird to me, that we would document the fact that you can't do that. There's no UI for it, there's no internal setting of expectations that the feature should exist... but users can also bring outside expectations with them, and we can't really control those.

MBB232 commented 4 years ago

We are quickly derailing in tech stuff again (would that be meta-meta-documentation-communication?)

Devoting some time to process initially is a necessary evil with Github and the like, though, because without those nailed down keeping track of the "real" tasks can be impossible.

Yes, you could probably have updated the whole manual in less time that it toke to answer my questions. Hopefully my questions have been of some help; you found a way to have the documentation translated. And having verification of the manual in Github should make it saver for us noobs to make changes without fearing to break things.

how difficult Github makes discussing code or giving feedback other than via the pull request system. I can see all of your MBB232-AboutDoc branch, I can even compare it to the openshot-qt:develop branch... but I can't offer any feedback on specific lines within the files

Github allows pull requests with a review mode, so I suppose I should be using that. Is there a particular branch of Openshot that I should make the request against, or is that managed I guess I can make a pull request against your fork so you can offer comments or changes (or vice versa), or put up the document on an online OpenOffice hoster for collaboration and commenting.

I'd say, absolutely, let's get the meta stuff (the doc/AboutDoc/ parts) into a PR in the project repo, that way people have the option to start looking it over and generating feedback.

Thanks, I will do that then. I have not found out how to choose which files should be offered for a request; I want to offer the About_Doc, but not the About_doc_old. Do I need to fork out the files I want to offer again, and delete those not wanted or not ready? We'll no doubt run into other things that it should address. But as you explained before, they can be added in later pull requests.

My main question: should the technical stuff be split into a separate file from the page design? Is it becoming too long, or does that not matter because the Sphinx index lets people skip to what they want to read anyway?

MBB232 commented 4 years ago

And once that process has gotten started, let's move on to the actual documentation.

I tried starting by adding informative tables to Custom Profiles because I had run into it myself. Unfortunately my knowledge was lacking. Then SuslikV answere was to the point but a bit short, and yours was informative but a bit long. And parts turned out to be broken. So no cut-and-past-ing for me.
Now I do not really know how finish it, and is not ready for a pull request yet. Or maybe I should just replace the images and leave it for someone else to add to it. https://github.com/OpenShot/openshot-qt/issues/3427

A bigger concern, and perhaps even one that comes up more frequently, is when something isn't exposed in the interface (typically because it doesn't exist and/or work), but someone expects to find it anyway

I noticed that too, hence my proposal to include a FAQ. This may very well be on the Wiki, but it should at least be linked to from the documentation. (And then the Wiki FAQ can link back to the issues in the tracker if people want to participate or need more info. Perhaps include a poll or counter in how much the issue helped (Microsoft Technet that) to count how many people run into the issue.

Because the github tracker (and Reddit) are not very suitable as FAQ on it's own. Issues disappear quickly and are hard to search - if people even bother with that to begin with. I have bad google fu in general, but my guess is that if an issue is marked as closed-won't-fix, then a search on issue:Is-Open (default) will not give it in its results at all.

ferdnyc commented 4 years ago

I noticed that too, hence my proposal to include a FAQ. This may very well be on the Wiki, but it should at least be linked to from the documentation. (And then the Wiki FAQ can link back to the issues in the tracker if people want to participate or need more info.

I think that makes sense, as a "relationship tree" between the various resources, yeah. There's already a Learn More section at the end of the manual, which seems like a good spot to link to a Wiki FAQ page. (It already includes a link to the Issues section as a whole.)

I'd say we could link to the Wiki in general, but... there's so much there that isn't intended for endusers. (Or even if it was, it's not helpful to endusers.) The FAQ "page" could always evolve into an overview/directory, organizing multiple pages of entries by whatever grouping makes sense — topic, version, etc.

Perhaps include a poll or counter in how much the issue helped (Microsoft Technet that) to count how many people run into the issue.

Most likely not possible, alas. Github's wiki engine is extremely limited. (Which does have the advantage of keeping things simple.) Displaying static pages of formatted content with hyperlinks is pretty much its limit feature-wise.

I have bad google fu in general, but my guess is that if an issue is marked as closed-won't-fix, then a search on issue:Is-Open (default) will not give it in its results at all.

It's only slightly better than that, yeah, partly due to Github's stupid. The header of the results list does show a count of both open and closed matches ("# Open # Closed"). While only the Open list is shown by default, you can click the Closed count to switch to that list instead. Which is nice and all, except that there's almost nothing about those header items that would indicate they're clickable, so a lot of users won't even notice the "Closed" listing, understandably. And of course even fewer will actually look at it.

OTOH, other users will heroically root around until they find a 5-year-old closed issue that sounds vaguely like what they're experiencing — even if the situations have basically nothing in common beyond a particular keyword, or happening to occur in the same part of the interface — and they'll add a comment there rather than opening a new issue. (See e.g. #24 (!) which I locked in February as a response to its most recent resurrection. Locking an issue is drastic, but it's the only sure way to prevent further necromancy.)

I'd appreciate the sentiment, if I really believed they were driven by some noble — if misguided — reluctance to create duplicate issues. But I suspect it's more often because they just don't feel like filling out the bug report template with the information we request. Which means if they do have a valid issue, we'll just end up having to grill them for those details piece-by-piece instead of getting it all up front.

ferdnyc commented 4 years ago

Hopefully my questions have been of some help;

Absolutely. I suppose maybe it's different for everyone, but I know at least in my experience, you can "know" something for yourself, but you don't really know whether you have the information available in an organized fashion until you try to communicate it to someone else — in any fashion. That's when you spot all of the gaps, the contradictions, etc.

you found a way to have the documentation translated.

Better! I finally took a good look at Sphinx's translation support, and I discovered it sucks so bad we probably shouldn't bother with it. Which means no more effort wasted there. (And I found out how we can configure it if we need to share images, create localized versions of images, etc. if any translated versions are eventually produced.)

And having verification of the manual in Github should make it saver for us noobs to make changes without fearing to break things.

One of the great things about the PR system is that you don't really have to be too concerned about that. The only way to break anything in the project code is by merging a PR, and all of the checks and test builds and etc. are there to try and catch any potential problems before that happens, and human eyes looking over the PR hopefully catch any other issues.

All of which is to say, not only does a PR have to be problem-free before it's submitted, but sometimes a PR can even be submitted with known problems, as a way of getting feedback or ideas on how to solve them. A number of open PRs are marked "WIP" in the title, to indicate that they're broken or incomplete in some way and shouldn't be merged.

The idea of the automated documentation build is to make it easier for people to experiment and try different things in their PRs, then see the results for themselves. I'm hoping it'll encourage more PRs that initially break things, then evolve to include the fix.

Github allows pull requests with a review mode, so I suppose I should be using that. Is there a particular branch of Openshot that I should make the request against, or is that managed

You do have the option to choose when you open the PR, but it should nearly always be the default (develop) unless there are some special circumstances. That's where all of the contributions get pulled together, then the releases and etc. will be branched from there.

I guess I can make a pull request against your fork so you can offer comments or changes (or vice versa), or put up the document on an online OpenOffice hoster for collaboration and commenting.

Oh, definitely please don't do that. A PR to the main repo is exactly that: an open invitation to other users/developers to look things over and give feedback. A PR to my fork is just a way of passing some code to me, nobody else will see it. (And they really won't see offline files, or be able to leave feedback readily and in the manner they're used to. Better to avoid the additional-user-accounts thing wherever possible.) If anyone wants to look at the formatted docs from the PR and isn't set up to build them locally, they'll be able to download the ZIP artifact produced by the Github Action run.

I'd say, absolutely, let's get the meta stuff (the doc/AboutDoc/ parts) into a PR in the project repo, that way people have the option to start looking it over and generating feedback.

Thanks, I will do that then.

I have not found out how to choose which files should be offered for a request; I want to offer the About_Doc, but not the About_doc_old. Do I need to fork out the files I want to offer again, and delete those not wanted or not ready?

Basically you want to part them out, yeah, but into a new branch created for the PR, which you'd then submit from. Primarily that's needed to produce a "clean" PR with the changes you want to submit. You don't have to delete anything, because that branch can stay as-is while you surgically bring the parts you need over to the new branch.

If you were to submit a PR from your existing MBB232-AboutDoc branch as it exists now (which you could do right from this link), here's what the PR would contain: https://github.com/OpenShot/openshot-qt/compare/develop...MBB232:MBB232-AboutDoc

Generally a PR like that won't be accepted by a project, and depending on the project could even be met with varying degrees of hostility. When working on something in a personal branch, it's fine, but all of the incremental changes need to be consolidated ("squashed", in Git terminology) into as few commits as possible, that way the project history stays organized and readable once they're merged. (A maintainer can squash an entire PR when they merge it, but it's not ideal and some are reluctant, especially if multiple files or commits from multiple sources are involved. It's preferable if the submitter handles that.

The web abounds with advice on cleaning up branch histories and prepping commits for submission. There are all sorts of git techniques for doing it, but they're mostly tedious command-line processes.

Here's probably the easiest way you can approach it, even if it's a little brute-force. (It'll still require a Git tool like Github Desktop, since you'll need to have the actual files on your local computer to work with them, rather than using their web client.):

  1. Clone your fork locally using a Git client, if you haven't already
  2. With the source branch (MBB232-AboutDoc) checked out and the files in whatever state you want to submit, make a copy of them somewhere OUTSIDE the Git directory.
  3. Switch over to the develop branch of your fork, which won't be too far behind the central develop brach.
  4. Create a new branch based on develop.
  5. For each file you want to create or make changes to, take the updated version you made a copy of from the MBB232-AboutDoc branch, and copy it back over the version in your new branch.
  6. Commit all of the changes in each file or group of files to your new branch as a single commit, with a good commit message summarizing the contents. (For a newly-added file, especially documentation, that doesn't have to be anything elaborate. A one- or two-line description is fine. But it can be more than that when necessary.)
  7. Push that branch back to your fork, so those commits are present on Github as well as your local PC.
  8. Open your PR from the new branch. (You'd normally do this part from their web interface, though it's possible some tools like Github Desktop also have the ability to open PRs.)

That way the PR will include just the consolidated commit(s) from that branch.

It's a hassle, for sure, but the alternative is a PR that's a bigger hassle for the project maintainers.

My main question: should the technical stuff be split into a separate file from the page design? Is it becoming too long, or does that not matter because the Sphinx index lets people skip to what they want to read anyway?

There is such a thing as too long, for sure, but I don't think it's reached that point yet and there are some advantages to keeping everything on one page. (For starters: you can quickly locate something in the text using the browser's page-search function. Searching across multiple pages isn't as convenient.)

ferdnyc commented 4 years ago

If you were to submit a PR from your existing MBB232-AboutDoc branch as it exists now (which you could do right from this link), here's what the PR would contain: develop...MBB232:MBB232-AboutDoc

Don't worry about all of the control files and configuration changes, BTW. (Most of the "15 files changed" in that listing, IOW.) You don't need to deal with that stuff. Some of it has already been merged to the project repo. For the other bits I'll either do the same, or I can attach them to your PR before it's merged.

ferdnyc commented 4 years ago

I tried starting by adding informative tables to Custom Profiles because I had run into it myself. Unfortunately my knowledge was lacking. Then SuslikV answere was to the point but a bit short, and yours was informative but a bit long. And parts turned out to be broken. So no cut-and-past-ing for me. Now I do not really know how finish it, and is not ready for a pull request yet. Or maybe I should just replace the images and leave it for someone else to add to it.

3427

That's a perfect example of something where I have feedback regarding certain specific points, so it's much easier to do that in a PR context where I can attach notes and suggested edits directly to the content. Especially since they're just iterative tweaks. Generally I think it's good stuff, and would only take a little polishing before it'd be ready to go in.

So, like I said, that's actually the exact sort of change that IMHO would be ready for a PR (perhaps a draft/WIP PR, if you prefer), to give others a chance to look it over. And hopefully they/we/someone can help with the parts you're not completely satisfied with yet.

SuslikV commented 4 years ago

@ferdnyc It's funny that you already wrote more strings here, than docs itself required...

MBB232 commented 4 years ago

When working on something in a personal branch, it's fine, but all of the incremental changes need to be consolidated ("squashed", in Git terminology) into as few commits as possible, that way the project history stays organized and readable once they're merged.

I guess that makes sense. But so much for me trying to come up with a useful description for every little change so others would know what I was doing.

  • Clone your fork locally using a Git client, if you haven't already
  • With the source branch (MBB232-AboutDoc) checked out and the files in whatever state you want to submit, make a copy of them somewhere OUTSIDE the Git directory.
  • Switch over to the develop branch of your fork, which won't be too far behind the central develop brach.
  • Create a new branch based on develop.

So much for working in the cloud. I have not installed a desktop version yet. After spending so much time learning rest, github online etc I was hoping to skip offline desktop commandlines for now. (About how much MB would it try to download anyway? Are there video files for testing in it somewhere). I am sure I must learn some day, but hopefully not today.

Would it not work the same if I were to create a new branch from my ~develop online? And re-upload my files to there? (Can the comments not be stripped out when merging with my own branch? I presume you do want to see comments for why each file is added (and what it contains), and be able to reject them separately.

I will leave out your files, as otherwise they would get my name attached, right?

And I should probably sync my main branch with the official one first? Or should I delete the entire project and re-fork from Openshot? https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser

ferdnyc commented 4 years ago

@ferdnyc It's funny that you already wrote more strings here, than docs itself required...

It's a gift?

ferdnyc commented 4 years ago

I guess that makes sense. But so much for me trying to come up with a useful description for every little change so others would know what I was doing.

Yeah, that level of detail is useful for the process, but not so much for posterity. The commits that get merged into the project should ideally just represent a full set of changes to achieve some high-level goal, so that someone years from now can find the commit that added the "Are you sure?" dialog when canceling an Export, or added the Importing and Exporting section to the user guide and see the edits that went into each change as a combined unit. The process by which the submitter got there isn't relevant long-term.

So much for working in the cloud. I have not installed a desktop version yet. After spending so much time learning rest, github online etc I was hoping to skip offline desktop commandlines for now. (About how much MB would it try to download anyway? Are there video files for testing in it somewhere). I am sure I must learn some day, but hopefully not today.

It'd be a lot, though it's more because of the history than the contents. The full repo is only 102MB, but the full git clone clocks in just shy of 400MB, the difference being the git history. It's possible to do all sorts of "shalllow" clone operations that avoid pulling down the complete history, to reduce the size... but that's definitely all commandline-only type stuff. I just ran a very shallow clone:

$ git clone --shallow-since 2020-01-01 -b MBB232-AboutDoc --single-branch \
https://github.com/MBB232/openshot-qt
Cloning into 'openshot-qt'...
remote: Enumerating objects: 3499, done.
remote: Counting objects: 100% (3499/3499), done.
remote: Compressing objects: 100% (2431/2431), done.
remote: Total 3499 (delta 1255), reused 2991 (delta 1041), pack-reused 0
Receiving objects: 100% (3499/3499), 60.71 MiB | 6.55 MiB/s, done.
Resolving deltas: 100% (1255/1255), done.

...And that's only 60MB downloaded (163MB on disk, git compresses transfers), but also definitely overcomplicating things.

Would it not work the same if I were to create a new branch from my ~develop online? And re-upload my files to there? (Can the comments not be stripped out when merging with my own branch?

Yeah, that could work actually, in two possible ways:

  1. Self-PR-and-squash
    1. If you create a new branch, you can submit your current MBB232-AboutDoc branch as a PR to your own new branch, same as any other PR. (It's a bit tricky only because GitHub will try really hard to direct any PRs to the upstream default branch, and if you want to submit anywhere else you have to double-check every step of the way that it's still targeting the right fork/branch or you'll end up with a new OpenShot PR.)
    2. When you merge that PR into your new branch, you have the option as the maintainer to squash the PR. (Only option will be a single commit with all of the submitted changes, though.)
  2. Or, as you say, you could create a new branch, and then because it's only a few files you could re-upload the modified versions, or even recreate the edits just by copy-pasting the entire contents of the file as it exists now in the MBB232-AboutDoc branch into an edit session targeting the new branch.

With so few files, and with other changes that you don't necessarily want to include present in the source branch history, I think the second option is probably the better way to go.

I presume you do want to see comments for why each file is added (and what it contains), and be able to reject them separately.

Can't really do that anyway, at least not easily. A PR is an all-or-nothing affair. Generally a commit per file is a reasonable grouping, but it depends. For example, adding a set of screenshots for some related topic would involve adding the new images, plus making edits to one or more RST files to insert the images, and all of that should probably be done in a single commit.

I will leave out your files, as otherwise they would get my name attached, right?

Yeah, and the last thing you want is someone chasing you down 6 months from now complaining that adding this module or using that version in a config file is causing them problems or whatever. (It happens! Not physically for the most part, but online stalking is a real thing!)

And I should probably sync my main branch with the official one first? Or should I delete the entire project and re-fork from Openshot? https://github.com/KirstieJane/STEMMRoleModels/wiki/Syncing-your-fork-to-the-original-repository-via-the-browser

Your fork is recent enough that, especially since you're adding files, you probably don't need to bother. I definitely wouldn't delete the fork, then you lose the current state of things and there's a much bigger risk of losing your changes too!

Git is smart, it knows to compare your PR branch with the project in whatever state it existed when you created your fork, with any subsequent changes applied on top of that. The only time there'll be any issues is when you're submitting changes to files that have also been edited in the main repo, because those edits can conflict. (Even then it's usually not too much trouble to resolve any conflicts directly from the PR, Github has a tool for that.)

MBB232 commented 4 years ago

@ferdnyc

Git is smart,

GIT just outsmarted me , when I propose a pull request for my new dir, it wants to include changes to the main branch too.
-which includes the unfinished profiles.rst with its many changes. (My first attempt at Github)

PS: Luckily it did not overwrite my additions when I synced with Openshot. But if I delete that file, it probably wants to delete the original from the Openshot branch if they got merged.

-- https://github.com/OpenShot/openshot-qt/compare/develop...MBB232:MBB232-PullRequest-AboutDoc?expand=1

ferdnyc commented 4 years ago

Yeah, it turns out those commits are on the develop branch in your fork, so they got included in the new branch you created as well.

That makes things a bit trickier. Looks like you will need to sync up your fork's develop branch, at least, to the project one.

ferdnyc commented 4 years ago

That makes things a bit trickier. Looks like you will need to sync up your fork's develop branch, at least, to the project one.

Significantly trickier, in fact, because you can't just update the branch -- those commits will still be there, and as long as they are they'll get included in new branches. Your develop branch needs to be rewound to the point where it diverged from the project repo, then synced up with the new upstream commits.

Um... Hmm. If you want to give me write access to your fork (Settings > Manage Access > Invite a Collaborator in the desktop web interface), I can fix it up for you and reset the new branch to a clean state. I don't think it's possible to fix from the web interface.

(If you don't want to, then smart choice! I'm not planning to mess anything up, at least as far as I know, but things happen...)

MBB232 commented 4 years ago

Thank you for the offer. But like you say, everything would have to be rolled back, because that was literally my first action, the file that created my fork. So I deleted the whole fork and started over. Not that I do not trust you, but this seemed faster and simpler. I immediately created 2 branches, and maybe I should create a backup branch too - though github seems to default back to the develop branch.

I also created the pull request, hopefully 2 changes are acceptable. (I needed the first to create the subdirectory). Your checking mechanism seems to work, and all checks were passed. https://github.com/OpenShot/openshot-qt/pull/3463

MBB232 commented 4 years ago

Thanks for adding your feedback on the about-doc. I noticed a 'commit suggestion' button under some of your comments. Is that to accept them into my request? Should I click on that to add them for the ones I agree with?

MBB232 commented 4 years ago

I left it for a while in case others wanted to comment too.

I merged most of the easy things you committed. How do I make the other changes that you suggested and I agree with, by making changes in my own fork? Or would that overwrite this topic?

Should the copyright notice in the template be redone in the old format too? As the headers are hidden, they are not processed by Spinx so the single-line does not really matter.

Good that you caught the name of the template, I guess I have a bad case of CamelType writing 😁 I must have made the mistake when recreating the 'clean' version , because I tested it in the original. Do you want Documentation_About rewritten without capitals too?

Because I recreated my fork, I can confirm that the action is send with the updated source too. It is not automatically activated. Github_Workflows Github_Workflows2

MBB232 commented 4 years ago

OT: Any way to set GIT preferences for the issue tracker? Can get it to show the name of the last user to comment, and by default auto-sort on latest-comment rather then creation date? (It keeps resetting). And how to never auto-hide conversations in pull requests, it hid a lot of your comments like easter eggs.

MBB232 commented 4 years ago

@ferdnyc While waiting for approval, I've gone back to my 'profiles' page. https://github.com/MBB232/openshot-qt/blob/MBB232-profiles/doc/profiles.rst

I don't think there is much point in updating the images as the interface for them does not seem to have changed. (We could simply re-save the jpg as png, but not sure if that is allowed, as they contain no exif data) If I do, I'd rather use a box-mark to highlight the important fields and buttons, as a single '1' seems a bit odd.

However, the profiles page seems to be the only page that details any of the video export options, and the "advanced video export options" tab is not covered at all. There is a 'Import and Export' section, but it only covers the export of cuts to EDL/XML for other editors. Perhaps the profiles page should be renamed to Profiles&Video Export , and the other to "Editors Import& Export" or simply "Exchange with Other Editors"?

'Export' may seem straightforward, but the difference between High/medium/low quality should probably be explained a bit (Do you know (where to find) it?) , And the use of hardware encoding - broken though it may be- should be mentioned.

While the 'advanced' tab it is an odd interface and probably mostly used by experts, it is the only place where you can choose to export only part of your project.

I think that considering the importance of setting the correct profile at the start of the project, profiles should at least mentioned in the Quick Tutorial' page too?

MBB232 commented 4 years ago

I've also made a set-up for a 'preferences' page as it was not covered at all.

I have included paragraphs and screenshots for all tabs, and may add some more suggestions and things that (I think) I know.

However, between the work in progress, bugs and my general lack of knowledge about the program, I do not feel comfortable describing what all the functions can do. Hopefully someone experienced can step in?

https://github.com/MBB232/openshot-qt/blob/MBB232-preferences/doc/preferences.rst