Openshot-qt: Call for Volunteers: Documentation updates

[ferdnyc]

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)

• Significant portions of OpenShot have changed greatly since 2017, including the Preferences (which are virtually unrecognizable from two years ago, in some of the tabs).
• New features have been added, including hardware encoding (for both export and animated titles) that could do with at least a cursory treatment in the manual.
• Even some features that aren't new could still do with expanded documentation:
  
  
  
  • Export options
  
  
  • Keyframe animation generally (which is really crying out for an illustrated step-by-step tutorial)
  
  
  • Effects
  
  
  • Transitions.
  
  

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]

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:

• Sphinx video https://www.youtube.com/watch?v=ouHVkMo3gwE
• github text howto https://opensource.com/life/16/3/submit-github-pull-request
• github video howto https://www.youtube.com/watch?v=rgbCcBNZcdQ

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]

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

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]

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]

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]

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]

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]

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

* 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]

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

[befocken]

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

Well I was mislead then :D

[ferdnyc]

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:

• A FAQ would be a good thing, agreed
• IMHO the wiki is probably the right place to maintain it
• And as an aside, the existing wiki content could really use a good spring cleaning

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]

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]

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]

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!\)

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]

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]

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 \

(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]

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]

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]

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]

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]

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:

• 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.)

• Image references can be written as "globs" rather than using an explicit extension, e.g.
  ```rst
  .. 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. (They present a hypothetical scenario to illustrate how that would work and what use it would be.)

[MBB232]

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]

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]

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]

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]

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]

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]

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

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]

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]

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]

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]

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]

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]

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]

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]

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]

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

[MBB232]

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]

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

It's a gift?

[ferdnyc]

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]

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

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]

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]

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]

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]

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.

[MBB232]

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]

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

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

[MBB232]

@ferdnyc
I found the branch with the code
https://github.com/ferdnyc/openshot-qt/tree/docs-markup/doc
But it seems most files are older then the current versions.

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

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 did a test by uploading your file of main_window in my branch to see what worked.
(I downloaded the HTML from the actions, really helpful :-) )
https://github.com/MBB232/openshot-qt/actions/runs/107264862

It seems your CSS for gui-label made it upstream, but your code for the hotkeys did not. At least, it is not showing for me in Edge(old) and Chrome.

That while the conclusion from your topic seemed to be that you wanted to keep the hotkeys, but maybe not the guilabel-buttons.

To make it more confusing, that is how the Github ReST viewer is showing it.

[MBB232]

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:

And even that one wants an update 🤣

[MBB232]

Perhaps we should also ask AndrewBullen for advise on the manual and/or the FAQ/Wiki. He is quite active on the Reddit and has a few interesting tutorials about OpenShot. So he may know what else people run in to and need more explaining.
https://www.reddit.com/user/AndrewBullen/

[MBB232]

How to tag images?
You wanted copyright attribution inside the image. I got Exiftool, but there does not seem to be a single standard for field names. There is a field for 'software' but that is the program the image is created in. Nor is OpenShot the author.

Should we go
rights="OpenShot GPL3+"

Or
Copyright="OpenShot"
License="GPL3+"

or both?

[ferdnyc]

That green circle callout is actually in the repo, as docs/images/circle.svg.

And even that one wants an update 🤣

All of our title files come up the same way, that was a relatively recent Inkscape change. (Meaning, like, 2017 or so. Relative is a relative term. :wink:)

[ferdnyc]

Sorry, I meant to get back to you on this more quickly.

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

It seems your CSS for gui-label made it upstream, but your code for the hotkeys did not. At least, it is not showing for me in Edge(old) and Chrome.

That while the conclusion from your topic seemed to be that you wanted to keep the hotkeys, but maybe not the guilabel-buttons.

Oh, none of 1354 was incorporated. There was I believe, a PR for those changes but it was abandoned. (For... Reasons™.)

The guilabel styling shows up because it's built into the theme, and I still think kind of sucks — that was one of the remaining issues there. It really needs to be improved if we're going to use it. The keyboard key styling was customized, so it got left behind on that branch. But I could resurrect that part easily enough.

If those roles are going to be used in the manual (and generally I feel like they should be, semantic content is always a good idea), IMHO we need to improve the styling for guilabel, menuselection, and filename or whatever it's called. (That red is... Yikes.)

All of which is doable, and the primary difference between then and now is that now I have commit access to the repo, so it can be done pretty easily.

I'll restore the keyboard styling tonight and see what I can come up with for the rest.

[ferdnyc]

How to tag images?
You wanted copyright attribution inside the image.

I honestly don't remember saying that, I may have misspoken if I did. I really don't think that's necessary, the commit that adds the image to the repo serves as a statement of ownership/availability. (As long as the commit author created those images. Which is why it's important not to use any images without permission.)

And if we DO incorporate any images covered by an outside free licence, that license statement needs to be in the repo. ...Maybe _that's_ what I was talking about, but I just meant adding the license to the repo as a text file. Like the one that's somewhere in I think the src/images/Humanity directory, for the icons we bundle from that collection.

[MBB232]

@ferdnyc

the commit that adds the image to the repo serves as a statement of ownership/availability. . Maybe that's what I was talking about, but I just meant adding the license to the repo as a text file.

I remember asking, but you were a bit long in your answer. 😉
You did state you wanted license contribution on the images, though not clearly how.
The only way I could imagine that was on the images, either with a copyright logo on the image (ugly) or a meta tag.
If you want people to register in a file, or license is assumed automatically upon upload, then that needs to be covered explicitly in AboutDoc.

The guilabel styling shows up because it's built into the theme, and I still think kind of sucks — that was one of the remaining issues there.

I agree. And I don't think it is necessary, I think about everyone will recognize menu options like File and Edit.
Filepath may be useful, but that red? It should be white on black.
There is also .. code-block:: console which is basically the same thing.

People probably recognize keys too, but they look really cool in the table.
And as :kbd: is recognized by github too but gui-label is not, it adds consistency to use that one but not gui-label etc.

If those roles are going to be used in the manual

_If_ they are used, they are going in the meta-docs. That is where that missing Rest custom-syntax file comes in that you complained about.

I'll restore the keyboard styling tonight and see what I can come up with for the rest.

Thanks, then I'll add the new hotkeys tomorrow.

I think I can then offer up some pages for pull/review, as others will need to add technical details that I simply do not know.
Do you want them as separate requests, or as one block? (I do want to keep them separated from AboutDoc, as that dir is still in progress)

Do you really still want all jpgs replaced by png? To me, the interface has not changed that much. (The only change coming seems to be on hold, so I stopped waiting)

[ferdnyc]

I remember asking, but you were a bit long in your answer.

Weird, that doesn't sound like me. :angel:

The guilabel styling shows up because it's built into the theme, and I still think kind of sucks — that was one of the remaining issues there.

I agree. And I don't think it is necessary, I think about everyone will recognize menu options like File and Edit.

Well, yeah, but that's :menuselection: — which we didn't like because it's _understyled_. And it is useful for pointing to deeper selections like Edit > Preferences or Title > Animated Title. But i think just styling it bold, like the non-role-based mentions are formatted now in the manual, will suffice.

:guilabel: is for controls in the interface (buttons, primarily), and in those cases indicating that someone should click Save or whatever is helpful. I just need to tone down the "decorations" a bit.

I think I can then offer up some pages for pull/review, as others will need to add technical details that I simply do not know.
Do you want them as separate requests, or as one block? (I do want to keep them separated from AboutDoc, as that dir is still in progress)

Definitely, on the latter. As for the former, up to you really. Logical units, I guess. If you make a significant amount of changes to a single file, submitting that as its own PR may make sense. If there are just a relatively few/small changes across multiple files, theose could be grouped together. But it's probably fine either way, if everything's a documentation change.

Do you really still want all jpgs replaced by png? To me, the interface has not changed that much. (The only change coming seems to be on hold, so I stopped waiting)

Oh, no definitely not. Not If the image isn't otherwise being changed — those can be left as-is. When something's being updated, _then_ it makes sense to make the new/replacement one a PNG.

[MBB232]

@ferdnyc
Sorry for going AWOL on you.
I was letting your comments on profile settings sink in, Because I don;t think I really _understand_, let alone explain it correctly _to others_. Underwhile I was working on that FAQ we were talking about.
Then it was nice weather last week, so too hot to stay inside. Afterwards, it toke some time to get back into it.
I notice we have a new contributor. Good, cause I think we could use the help.
But does this mean I need to be more careful with the pull requests?
Can we have an 'incomplete' branch of the manual on the Openshot github that we can push things through that are not finished, so everyone uses the same version?

[MBB232]

As I said, I have been trying to whip up that FAQ we were talking about.
which quickly devolved into a hell of its own.
https://github.com/MBB232/openshot-qt/wiki/FAQ

I was quickly loosing oversight, and wanted a place to dump the issues not suitable for the manual, yet to be covered or often asked regardless.
Also I wanted a FAQ to link to.

The Process
The default markup choice of GIT is MarkDown, which does not support automatic Table Of Contents.
After the docs, the obvious choice would have been ReST, but I could not find how to let it make TOCS either. (All google results return to Sphinx, which did not seem to work)
Workarounds exist, but would involve cloning the wiki locally and running a script every time new titles are made. It may be possible to do it with Workflows, but I do not know how and do not want to waste time on now.

The MediaWiki markup does support automated TOC tables at the head of each document.
And the markup buttons do not work for it, so I had to study. Some it is simple but different, other times it supports parts of HTML code.

Turns out, Github Wiki does NOT support all those things Github Issues does, like auto-link issues and hosting of images.
It ALSO does not support some of the main plugins that make Wikipedia usefull. It can not include other wiki pages (for 'security reasons' and I can not make it list pages by category.
And they have practically no documentation. https://help.github.com/en/github/building-a-strong-community/editing-wiki-content

Of course, Wiki tutorials rarely tell when commandos belong to extensions, so it has been trial and error.

For now
I have decided to go for dumping ALL topics in one WikiMedia page, so that the TOC will contain all topics.
For complex issues with longer descriptions and images, use separate pages linked from the FAQ, But at least they will be indexed this way, if not searchable.

Content-wise, I've divided it into 4 sections with subsections.
The idea is to simplify the questions.
Then responses quoted from given in the issues (credit can be in footers) and include images if suitable.
Followed by linking Issues, when relevant for background information. (Some may be closed)

But all can use heavy editing, and maybe someone with better Wiki-Fu can apply some markup fixes.

* The future*

Lets first see if people use it. Hopefully the number of repeated 'simple' questions should go down in the Reddit.
(Is there an Action for a page counter image?)
If it is a success, you may want to move it to a real wiki server hosted on the website, move it to another Sphinx like the Manual, or do something else entirely.
(Heck, maybe someone wants to write an interactive FAQ bot)

[rexdk]

I confess I have very little interest in spending many hours of time installing the software necessary to work on the user guide on github. But I am interested in contributing to the content of the user guide.

I have started writing up clip properties on a cms, which means that I can edit whenever I get a spare moment, whereever I am. Being wysiwyg makes it easy for me.

You can find what I've done here:
https://drking.org.uk/openshotguide/clip-properties/

I think the content is a lot more detailed than has been available so far, and it would have helped me greatly if it had available when I needed it. But you may disagree.

If you think this is helpful, I'll carry on. Do let me know.... I don't want to waste my time if it will never be used.

This issue/thread is now so long that it's getting confusing, so I'm not sure what the current state of play is.

[MBB232]

Hey, I was _just_ going to take some screenshots and point out issues that were unclear, before I got roped into this 😢

Came across this open letter by Andrew Bullen on Reddit addressing general issues with OpenShot.
https://www.reddit.com/user/AndrewBullen/

One of the mentioned issues is a FAQ, so I was not alone in that opinion.
Another is a central place for tutorials. I agree, and I propose we use another Wiki page to link tutorials. Categories could be text+video, and should be added tagged with basic/advanced and subject.
Could be some complete series, and some separated by features, and maybe some basic concepts about video editing.

I also propose to keep a Wiki page where we link to such reviews of OpenShot, if they are honest or contain benchmarks. As harsh as they may be, they can contain a lot of useful info for which features to fix first.

He also mentions performance issues due to settings, so that may be useful for better covering in the manual

Performance
Often complaints of poor performance, could implement the following Preferences suggestions:
Preview – That is misleading, it is not a Preview but a Profile setting. Many forum posts and tutorials also recommend changing the Profile to a lower resolution, when if using a Scale of None that will create unforeseen results and you state “It is best practice to always switch to your target profile before you begin editing”. Instead could replace that with an actual Video Preview preview quality setting, offering Final (100%), High (75%), Good (50%) or Draft (25%).
Performance – Hardware Acceleration complaints with Linux and still buggy and with limited support currently for Windows and Mac, and can only recommend they could all be fixed.
Cache – Cache Limit’s small default of 250 is a reported cause and could consider options.
Size – The large file size issues could be due to the high default Video Setting of 15 Mb/s Bit Rate for all profiles, hidden in the Advanced tab, and in what is unclear is a configurable tab.

[USATechDude]

@MBB232 I would like to include the updates that you've made into the version of the User Guide that I am building in my repository. I've only modified a few of the files because I found that information in GitHub and Reddit. I'd like to start a the beginning and update the whole guide to align with Version 2.5.1.

@rexdk I would also like to include the updates that you have made so far. I found your Clip Properties guide very useful and I've added your information to my repository.

You can see what I have so far here:
https://github.com/USATechDude/openshot-qt/tree/develop/doc

If you have any other changes or updates, I would really like to see them.

[rexdk]

USATechDude

That's great, thank you :)
There are still some things that might help the user in clip properties in your stuff:

1. One example among many still in the original table: "Curve representing the crop height of the clip in percent (0 to 1)" - that is simply not true - the value is not in %, it is a fraction. 1 doesn't represent 1%, it represents 100%.. And it is not a curve - it is a single number.
2. I think that it is really important to explain to the user the order of calculation, and indeed its importance. Eg, a clip shot on its side on a mobile phone does not respond to "Scale" as you'd expect - it does not align with the sides of the screen - because rotation is applied last, not first. Probably a hasty early get-it-done programming decision I guess. I'll gladly talk this over in more detail - in fact I had intended to give clear examples - just not got there yet; I'll do that next.
3. You've kindly taken my outline box - but because it is not in the flow of the calculation of properties it now isn't defined correctly. It only works if it it defined at the correct moment of calculation.
4. It's now rather a long section - might it be simplified, while retaining the important info. Or might the various sections being separated onto different pages.
5. There is a serious bug in the Time property - it does not work; it's likely that my update to this property on my cms has missed you.. My view is that the user guide should be honest about bugs - if something doesn't work as expected you can save an awful lot of user pain. I'm aware that OpenShot has rather a lot of bugs (I've found 7 or 8 so far, and a couple more I haven't been able to pin down) - but that's even more reason to help the user :)
6. Jonathon has just amended some properties in his daily build. We need to be ready for the changes.

I'll gladly contribute some more. It would help to know what I can work on that no-one else is tackling. I've had a quick go at Custom Profile, again on my cms.

[rexdk]

@ USATechDude

Thanks for the useful amendments to your clips.rst. You might like to check out my revisions to the descriptions of crop and shear transformations (I think I originally had Shear wrong - that's the trouble with not having the info in the user guide ;). I've also written up about the order of transformations on a separate linked page with pics. I'm worried that it seems very complex - which it is - but the average user doesn't need that. So maybe the detailed description needs to go on a separate page, leaving the average user just to play with the settings - which mostly works of course.

Audio channels - I know what an audio channel is (left and right in stereo) - but I can't make sense of it here ;). As a user I'd like to know how Channel Filter numbers the audio channels, and what filter it applies (bass boost?). Yeah, yeah, a bit tongue in cheek - but I don't actually understand it currently :). I realise you have the original guide text here - do you understand it? I can experiment if not, or you may be able to ask a developer.

[rexdk]

@ferdnyc
I'm very willing to offer help here, but I don't understand how the user guide revision is organised. If I rewrite a section, it could be that someone else is working on the same thing. Because the guide needs substantial work, I think someone needs to be coordinating it - is that you, as the one who started the issue? Or the ever-helpful USATechDude? Thanks

[USATechDude]

@rexdk At the moment, I am coordinating the User Guide update. I’m receiving input directly from Jonathan and Matt. If someone else deeply desires taking on the task, I will provide all of the updates that I’ve already made.

Our thinking is that the Quick Tutorial is for the basic, simple information, with links to the topics later in the UG. The QT will provide enough information that a customer can create a simple video after just minutes reading.

The rest of the UG is an in-depth manual providing as much explanation possible. The consensus is that it is better to provide too much information than not enough. Each feature should be explained thoroughly and provide screenshots and examples if necessary.

After discussing the UG update with Jonathan and Matt, I am starting at the beginning of the UG the working page to page from the beginning. Other than the pages we’ve previously discussed, I am working on the Introduction, QT and Getting Started pages. If you have any updates for those pages, may I see them so I can include them?

All other updates that you’ve already made would be appreciated as well. If you will share your changes with me, I’ll add them to my repository. We can begin a discussion outside of GitHub to determine how to manage all the updates for each file. We can also figure out which topics need further information from the developers.

[rexdk]

Thanks. I'll contact you by email then for furhter discussion

[spaetz]

@USATechDude, you are coordinating doc updates now? Great!
My merge request has been sitting here for quite a while. Care to review and merge it? It is somewhat demotivating to have some changes prepared and ready for merging, with nothing happening with them and getting no feedback.
Perhaps the longish discussion on how to tech support the changes should not occur in this issue?
Anyway, I would be happy if somebody looked at my merge request. If not, that is fine too, I'll focus my attention to some other project then...

[rexdk]

We're more than a year on now, and progress is slow. There is a big entry barrier to anyone using Win10. However I have just managed to compile the guide on Win10, and in case it helps someone else:
Compiling OpenShot docs.txt

[rexdk]

Re compiling the user guide / my previous comment. It looks to me as if the existing sphinx-build routine (not just mine on Win10 but the original too) does not catch all the dependencies. I've found it necessary (if things don't work as they should) to destroy the _build directory before rebuilding. Yuk.

[rexdk]

@USATechDude

As promised, I've uploaded a copy of my revised User Guide. This is a substantial rewrite of most of the guide, with tweaks to the contents structure and css, and a whole load of appendices containing a lot of detail.

www.drking.org/osg

There's some stuff which is I hope obviously useful, like a sensibly ordered list of profiles that you can actually use. There's some very detailed stuff that might be overkill, like exactly what the 20+ bezier curves do, and how to achieve a constant power audio crossfade. And there's stuff that still needs improving.

I've been working from daily builds, and they are changing rapidly at the moment. For example, I meticulously documented the bizarre crop properties - but they've just been removed (a blessing to any user I think.)

So, as I have no insight into the ongoing developments, and there seems little current prospect of the live User Guide being updated, I think it's time for me to call a halt and move on to other projects. When you're ready to look at this again, do ping me - I'll try to help if I can.