Call for Volunteers: Documentation updates #2989
Comments
ferdnyc
added
help wanted
|
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). Tutorials that have helped so far:
What I have not found are the standards for the manual. 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?) |
That sounds like a great idea, @MBB232 — thanks! I'll try to help however I can.
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.
Ouch, well sorry to hear that! There's a pretty steep learning curve with Git, it's true. As a collaborative version control system, Github isn't a simple click-to-upload file repository. You've no doubt gotten the basic rundown in those resources you mentioned, but if it all still sounds confusing, don't worry: It definitely is. Even those of us who've been using Git for years still occasionally get thrown by some aspect of how it works. I'd be worried if someone didn't find it confusing in the beginning.1 But like I said in the intro, you can worry about as much or as little of that as you're comfortable with. And as I said earlier, the content is the important thing. If you prefer not to deal with all of that and just want to upload images or provide new content in comments on this issue, that'd work for me. I can submit PRs with your changes and mark you as the author. (Git is designed to facilitate giving proper credit in pretty much any situation.) Crap, this is already getting really long, so I'll stop here and respond to the specific items you raised in a separate comment. Notes
|
|
Addressing some specific points:
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.
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:
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.
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 ( Though, if you look at
That green circle callout is actually in the repo, as .style {
color: #aec255ff;
}And as far as using them in illustrations, the numeral in
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.)
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. |
In fact, now that I've tested it I see that the page layout has a width cap that makes |
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. |
|
I found a rest plugin for Notepad++ I also have more questions. One step ahead, two steps aside. :-) Copyright notice: License Do you want to start a separate thread where all permissions for documentation are collected? Tags Demo art in screenshots Images Does github versioning keep copies of old images too or only of text? I propose that images should include the name of the page they appear in. Unless they are used in multiple pages? syntax |
|
I'm using online github for now. 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?) 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? 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. I started to make some changes to better explain profiles, as I already ran into that myself and on the ask-reddit |
I can recommend this repo, where you can see all the different syntax of markdown :) |
|
@befocken The documentation isn't written in Markdown, it's reStructuredText ( |
Well I was mislead then :D |
|
Returning to some older items: Copyright & Licensing
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.
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:
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
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
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. 😉 FAQs and tags
Ah, see, now a FAQ is a very different thing. I think maintaining some sort of FAQ is probably a worthwhile effort, though such things unfortunately tend to get outdated quickly, and often end up starved for the resources (person-resources, time and effort) necessary to maintain them. Still, if we can manage it that'd be great. Partly for the sake of recency and timeliness, I don't think the FAQ should be part of the User Guide, though. They have very different purposes. The FAQ should probably live on the project wiki where it's directly editable by anyone if they have information on a topic that's not yet addressed. The User Guide can certainly link to the FAQ page/pages, either in a "Further Resources" type section, or maybe even inline when relevant features are documented. And, in fact, looking at the page list now there are several FAQ-like pages already there, most of them no longer very current. (Oh, and hey, turns out it was a wiki page that mentioned the documentation only being available in English! Knew I saw that somewhere.) Regardless:
Workarounds
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
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 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
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 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 Version control
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: 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
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 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."
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 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 |
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.
(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. 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? 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. |
|
About to finally poke my head in at https://github.com/MBB232/openshot-qt/blob/MBB232-AboutDoc/ and have a looksee. (Er... after I make some dinner. Yes, I am on the east coast of the US and it is just shy of 7am here. Yes, I mean dinner, not breakfast. What, can't a person be 12 hours late for dinner? I always have dinner when I read Github, everybody knows that!</DarkHelmet>) Aaanyway, assuming I can pull together 20 minutes of focus and finally do get around to preparing my 12-hours-late "evening" "meal", I'll be able to take a look. Sorry it's taken so long. (Edit: "Forgot" the "scare quotes". #ForGreatSarcasm!) (Edit2: Obligatory link to the "blog" of "unnecessary" quotation marks.) |
|
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 I also finally discovered the important difference between ` (left from 1) and ' (left to Enter). That it toke me an hour to figure out issues like that is probably the main reason that Programming does not appeal to me. |
Hah! Yeah, that one's pretty good, coders do love their many, many particular little symbols. Doesn't even come close to rivaling the amount of strife and anguish sowed by the whole "backslash vs. forward-slash" thing, of course. Stroke of genius, that one. Now, whoever decided to embrace (three) [different] {styles} of enclosing brace-pairs (four if you count <tag> format, thanks HTML/XML), with a completely different meaning assigned to each one... well, TBH I kind of feel like that was just greedy and/or cruel. (Hah, it's funny because we are terrible, terrible people!) Of course, it only gets really complicated once you bring our friends the ‘smart’ “quotes” into it, AKA "typographic" quotes, which ironically can't actually be typed directly on standard keyboards, so you have to rely on editing-software automated replacement features to apply those. (Hence the "smart" in "smart quotes", which I have to assume was meant ironically because all software is extremely stupid, and literal to a fault. If sometimes so convoluted that it can appear to be performing some sort of artistic interpretation of the user's instructions more than actually following them.) Case in point:
You're referring to The reason 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: 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 Also, these 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 |
|
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? |
|
Anyway, having performed the |
|
Oh, hey that's nice. Turns out running The root (I realize |
|
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 |
|
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:
|
Titles are underlined
Rest being what you explained it was, I was expecting it to be less sensitive then HTML, not more.
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 ::
They are not supposed to be syntax at all They were supposed to be commented out plain text lines 😢
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. 😢
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? 😜 ) |
Well, they really /should not/, it is just meta-documentation for beginners that want to help at the documentation. 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! 😒 )
Glad my stumbling in the dark let you hit on something important. I noticed that documentation filenames are connected with underscore _ but images are connected with dash -
Very cool from a technical perspective, but a nightmare in making for maintenance. 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. Speaking of filenames, I forgot to address this
Clearly. The only way to go is the European date convention of DD-MM-YYYY.JPG. |
|
Also we both managed to fill several pages on the technical side, but what about the content? 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
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. |
Weird, that doesn't sound like me. 👼
Well, yeah, but that's
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.
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. |
This is a smallish attempt to improve openshot's sparse documentation (issue OpenShot#2989). The getting started page only contains an installation description, so name it so. Improve the quick tutorial somewhat (at least according to my taste) but still keep it quick. Improve the start of the "Files" pages somewhat. far more needed is a description of export options that is useable for end users but that is another task.
This is a smallish attempt to improve openshot's sparse documentation (issue OpenShot#2989). The getting started page only contains an installation description, so name it so. Improve the quick tutorial somewhat (at least according to my taste) but still keep it quick. Improve the start of the "Files" pages somewhat. far more needed is a description of export options that is useable for end users but that is another task.
This is a smallish attempt to improve openshot's sparse documentation (issue OpenShot#2989). The getting started page only contains an installation description, so name it so. Improve the quick tutorial somewhat (at least according to my taste) but still keep it quick. Improve the start of the "Files" pages somewhat. Make the import files table more consistent by nameing the method in the first column and actually describing them in a full senctence (interpunction) in the 2nd column. Add the actual toolbar button icon image to the table.
|
@ferdnyc |
|
As I said, I have been trying to whip up that FAQ we were talking about. 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. The Process The MediaWiki markup does support automated TOC tables at the head of each document. Turns out, Github Wiki does NOT support all those things Github Issues does, like auto-link issues and hosting of images. Of course, Wiki tutorials rarely tell when commandos belong to extensions, so it has been trial and error. For now Content-wise, I've divided it into 4 sections with subsections. 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. |
This is a smallish attempt to improve openshot's sparse documentation (issue OpenShot#2989). The getting started page only contains an installation description, so name it so. Improve the quick tutorial somewhat (at least according to my taste) but still keep it quick. Improve the start of the "Files" pages somewhat. Make the import files table more consistent by nameing the method in the first column and actually describing them in a full senctence (interpunction) in the 2nd column. Add the actual toolbar button icon image to the table. Similar things for the slice clips table on the clips page.
|
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: 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. |
|
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. One of the mentioned issues is a FAQ, so I was not alone in that opinion. 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
|
|
@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: If you have any other changes or updates, I would really like to see them. |
|
USATechDude That's great, thank you :)
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. |
|
@ 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. |
|
@ferdnyc |
|
@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. |
|
Thanks. I'll contact you by email then for furhter discussion |
|
@USATechDude, you are coordinating doc updates now? Great! |
|
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: |
This is a smallish attempt to improve openshot's sparse documentation (issue OpenShot#2989). The getting started page only contains an installation description, so name it so. Improve the quick tutorial somewhat (at least according to my taste) but still keep it quick. Improve the start of the "Files" pages somewhat. Make the import files table more consistent by nameing the method in the first column and actually describing them in a full senctence (interpunction) in the 2nd column. Add the actual toolbar button icon image to the table. Similar things for the slice clips table on the clips page.
|
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. |
|
@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. 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. |
|
I would potentially be interested in helping with this. I actually JUST got this software today (loving it!), so I'll need a little time to familiarize myself with it before I try to go writing any content for the manual. I actually only wound up here because I was looking for some kind of Preferences documentation, but if that's something that needs to be done that I can help with, it's the absolute least I could do to contribute to this amazing project.
|
|
There's some basic info about how the docs are made here My revised guide at was a substantial piece of work and took me quite some time. Unfortunately no-one has been able to progress this at all - I guess it's not thought important enough. So I bowed out and have put my efforts into other projects. My advice would be to try to make sure that your efforts won't be wasted before investing too much time. |
|
this thread is dated... if there is still need for volunteers I am available to help. I use openshot on a regular monthly basis. |
|
@jonoomph @JacksonRG @speedytechdev I'm here and willing to help, I use OpenShot to edit and publish YouTube videos on my YT channel. |
|
@DanTMan64 I took on this project beginning last year, but with my responsibilities on the OpenShot Help Desk and Reddit Community, I fell behind. I am happy to provide you with everything that I have to give you a starting point. I can also be your direct contact within OpenShot. If you are interested, please send me a message at [email protected]. |
|
Thank you so much for submitting an issue to help improve OpenShot Video Editor. We are sorry about this, but this particular issue has gone unnoticed for quite some time. To help keep the OpenShot GitHub Issue Tracker organized and focused, we must ensure that every issue is correctly labelled and triaged, to get the proper attention. This issue will be closed, as it meets the following criteria:
We'd like to ask you to help us out and determine whether this issue should be reopened.
Thanks again for your help! |
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 b1422e1.)
Documentation needs (working list)
Volunteers welcome!
Any volunteers who'd be interested in helping to improve the manual, both directly (writing documentation) and indirectly (soliciting, organizing, and copyediting contributions from developers) would be greatly appreciated.
Writing and editing OpenShot documentation
The source files for the manual are all found in the project repository (the
doc/directory), the preferred method for submitting edits would be via GitHub Pull Request but we can make accommodations for anyone who'd like to contribute but isn't familiar with version-control systems like Git.Generating a local copy of the manual requires only the Python-based Sphinx documentation system and the Sphinx RTD theme, which can be installed via
pip3 install sphinx sphinx-rtd-themeor using most package managers. I can provide support to anyone who'd like to contribute and needs help with installing and using Sphinx.The text was updated successfully, but these errors were encountered: