Another approach for ML tutorials and help files?

[kichetof]

Can you add links to the bold headings?

Hm, maybe I didn't understand what you mean on your last post. Do you want a global/menu page including all headings with links to specific explanations ?

I guess it would be good to have the modules also listed in the modules section.  I like how they are in their respective enabled menu, but could be confusing for some to not see modules in the module section.

Sure! I forgot to move modules sources to modules help folder! I'll update soon ... I remember why I didn't do it before. Modules add features to other menus (the modules menu offers no options other than activating/deactivating modules)

[Audionut]

Yeah I'd like to see all of the headers linkable.  Could then link to extended detail, tutorials, whatever.

I expect (some) people to look in modules for the modules.  Maybe just a list of the available modules in that menu, with links to the other menus where they are.

So I could look in modules, see dual_iso, and click the link that takes to the dual_iso help page.

[kichetof]

Yeah we're on the same way 
I would like to see a help structure like that! But... I don't know if bitbucket allow navigate links like ../ (need to test)

So I could look in modules, see dual_iso, and click the link that takes to the dual_iso help page.

What about modules who add multiple features in more than one menu? Multiple links? For the moment I get the name of the function and the name of the menu, I could links to it but ... same thing: navigation links. Need some tests

[Kokoe]

And maybe some suggestions concerning layout, structure, contents ....
What do you think? Too much? Too complicated? Too little? Wrong approach? Sounds good, doesn't work ... forget that, please ...

I can help create a semi-commerical manual that can be downloaded as a PDF or made as a professional, instructional video (having written quite a few over the decades).
Two suggested ways toward a <near perfect> manual (nothing = perfect or we'd ever want perfection).

Of course, versions/types of ML built to camera type is the biggest issue. So we either make one book with all Canon types in it or we make different books with different types. (This I would suggest as option 1 then it matches consistency with the ML site).
I don't have every Canon out there. I currently have 2 so there would have t be group of people who can supply me with every screen from the back of their Camera. No problem on quality, I suggest that I make a 'generic' screen and photoshop in the differences (20 years on photoshop so am no newbie here).

Suggest two options to discuss where one would be better before designing/making a concise but near perfectly understandable manual (which I can create as an internationally understood PDF (all languages), in video (again, all languages) and/or printed (if people prefer a printed one that I could charge at cost plus postage).

1.   'Ikea' approach to remove necessity to have to remove need for multi-language versions.
2.   LiveView Screen Approach. I would prefer a 'near to' Jonathan DeNicholas Vimeo approach where each screen is shown leading to a successful and working model.

Very Important to add the build used in the manual as a link under the PDF or Video link. Would be a bit of a support disaster to offer a manual that bears no relation to instructions (my only criticism of the Jonathan DeNicholas Vimeo where the current experimental build does not work to the instructions given there. (if any of those very lucky people out there are running the 27th April crop/experimental build please send me this ML holy grail, thank you).

I would divide the 'book' into these sections:

Cover would show full camera (or icon with words (e.g.: 5D Mkiii) and camera back with LiveView screen showing sample page

Section 1   Before installing ML. Terms. Conditions. Warnings. etc.
Section 2   Installing ML
Section 3   Setting up ML
Section 4   Using ML
Section 5   Modules Links with notes / Technical 'about' section
Section 6   Web refs to every ML link worthy of following or keeping an eye on.

May even be nice to update with latest examples of filming created with links.

My dime's worth. Please be as critical as you like.

(Hit 'modify button) - oh and before I forget. Many manuals are written from memory, recent or old, and then put out. I prefer to TEST, TEST AND TEST AGAIN like I was a newbie to test to see if what has been written 'actually' works. In 99% manuals there are flaws. It isn't the user. Its the manual writer.

[Walter Schulz]

I don't think we are on the same page here.
Main problem is how to maintain (long time support!) help files and tutorials for a project without timelines, schedules, milestones where menus/functions/workflows will change as devs are pushing cams abilities. And keep it open for participants to join in and drop out without killing the whole thing (see http://magiclantern.fm/forum/index.php?topic=11269 ). And make transparent what is valid or outdated for users unfamiliar with our project structure.
Video tutorials are quite difficult to maintain in this respect. I would prefer to start with smaller steps.

[Erik Krause]

So is the structure at bitbucket  ready to be filled or is this still a draft? Would be the next step to copy the content from the user guide thread to that structure or is the current content considered ok? I'd like to help if possible...

[Walter Schulz]

I don't think the structure was peer-reviewed that much. But this is what we have and Bitbucket projects are designed to make collaborative work and changes easier. So yes: Don't let imperfection be an argument for not getting started.

My not-so-eloborate masterplan was to pick an easy target (a tab/screen to begin with) first and fill it up with content (as good as possible but not aiming "perfect"). No, I don't think current content is considered to be ok. It lacks "help" content. Cross check with Redrock's approach:

Bitbucket now:

• Gain applied to both inputs in analog domain (preferred). -> That's shown in ML menu at the botton right now. Explains not that much.
Redrock:

• Analog does a great job of boosting the signal while retaining a low noise floor and hence, dynamic range. If you use an external preamp, set this parameter as low as possible otherwise, set it as high as possible without clipping (audio meters should be green). -> Looks more helpful.

Next: Then asking for approval from devs/regulars for correctness of technical stuff. And approval for grammar/spelling from native speakers.
Cream on top: Getting this one into nightly builds.

Next: Show progress and ask for support. I didn't intend doing all the stuff on my own. There are tons of people watching for progress getting their newest toys (Digic VI, VII, VIII) ML-ready  but unable to write code. Still offering help (where - at this point - coding is needed). Hell, let them put their keyboard where their mouth is. And there are tons and tons of ML users having a ball with ML. Call me a dreamer but I think there may be a few willing and able to pay back this way (judging by looking at rather mediocre ML tutorials on youtube/etc. their effort is better placed here).

That's just my 2 cents and I'm not "owner" of this.
Everyone willing to get the ball rolling again will be happily invited to do so. If you want to take the lead: Do it! And feel free doing it your way.

[Tullen]

Hi.

I was giving this a lot of thought for around a year ago, unfortunately I did not write it down but I still remember some of the main issues I was contemplating. My interest in the topic i still here and I would like to contribute if I can.

First of all (notwithstanding the fact that I do not understand all technical references) it seems that there are many approaches taken in this thread. Both thoughts about technical implementation and artistic presentation. I would suggest that the first step is to define what functions we are trying to fulfill. 

1- Is it just a database of some sort that can be filled with up to date guides for the different functions (including specifics for different cameras?)?
2- Is it an easy to understand overview and introduction to different functions for new and old users (that could of course be feed/linked to the mentioned database)?
3- Is it a greater tool that does not only make it easy to get an overview of what functions are available through Magic Lantern and how to use them on different cameras, but also if and how a newcomer could help develop the functions for supported and unsupported cameras?

Other functions to be specified is how easy it should be by whom to update the information, how easy it should be to see if the information is up to date and how much development is needed before a camera can be expected to have support implemented? I understand the last one is not an exact science, but could be simplified.

Different choices give different directions for implementation. For example, if choice 1 or 2 is chosen then it makes sense to filter the information by model, but if 3 is chosen you want people to see and be engaged with the functions that are currently not supported by their camera model.  EDIT! I realized that this is not necessary the case, will expand in next post.

I will try to remember the system (presentation wise) I had in mind when I was thinking about this before and come back with a suggestion. Feel free to suggest other functions that you think needs to be considered and or comment on the text above.

Cheers

[Erik Krause]

Well, my main concern is in camera help. We have the User Guide thread by Redrock which has very good content IMHO. I'd be happy to help copying over this content to the structure kichetof provided. I still have some questions, though: Is there a mechanism to transform the bitbucket structure into ML compatible .bmh files? The help system in ML seems to be working still. I copied the doc folder from a 2.3 stable to a recent installation and most of the pages show correctly. So I guess there is something which links the menu pages to .bmh files. How does that work and how is it maintained? 

If I understand correctly the current content in the bitbucket structure are the extracted help strings from .c files in /src/ and /modules/. It would be interesting to know whether it's possible to extract the content from the User Guide thread by Redrock in a similar way. In https://www.magiclantern.fm/forum/index.php?topic=11269.msg109944#msg109944 a1ex wrote he could do that if the formatting is consistent. Would this be a good point in time to do that?

[Tullen]

Is there more relevant material other than Redrocks guide and the pages with features, builds etc https://builds.magiclantern.fm/index.html?

[Tullen]

I will just reply myself and add some more questions.

How up to date and usable is the The sticky to end all stickies?
How up to date and usable is the German guide which also have been refereed to in this thread?
How up to date and usable is Redrocks guide since Walter writes "Linked User Guide covers outdated "stable" v2.3. There is no user guide for nightly builds available." in its last post from 2017?
Did I miss any relevant threads/sources?


I am currently in the process of documenting my experience as a first time user coming to the site (which in some ways are not far from the truth). This experience is based on two goals.

1. I have a Canon camera (where there already is ML development) and I want to find out what I can do with it, how to do that, what functions are yet to be implemented for my model and how I can help to develop them (as well as help ML community in general).

2. I heard about Magic Lantern and want to buy a Canon camera in order to use it. I am looking for the different functions (including understanding what they are and if I need/want them) supported by the different models (including resolution, bit depth support etc.) Since I do not need a production camera instantly I am also interested in what functions are possible coming to the different cameras and what would be required for that to happen.

With these two goals I am trying to build a user trajectory and understand how we might make it easier for the user. This of course needs to be coupled with the practical part of keeping development moving while updating information in an easy manner.

[Walter Schulz]

since Walter writes "Linked User Guide covers outdated "stable" v2.3. There is no user guide for nightly builds available."

Please don't quote out of context. Please link to quotes you are using.

This quote was an answer to reply #49 in this thread and reply #49 links to outdated User Guide found under -> Top of page -> User Guide -> User Guide.

There was no link to Redrock's "User Guide" post.

[Erik Krause]

The point is not how up-to-date anything is. The point is to have a structure that can easily be updated. At the moment we have quite a bit of information in the forums, so a user can find almost anything if he invests some time to search. There are two issues: There is no central point to start and there is no in-camera help. Of those two I consider the in-camera help the more important, since if you are out in the wild with no internet and need a particular function you get no information at all (actually I've printed part of the User Guide thread to have something with me in those cases, but that's tedious and I won't repeat it for new features).

As far as I investigated the User Guide thread is the best we currently have. It's a good starting point anyway and if there would be something that can easily be updated by the community and reviewed by the developers I have no fears the it will be an up-to-date manual soon. I like the idea to keep the sources for this manual together with the ML sources, which allows for a manual that fits any build version.

[Tullen]

Please don't quote out of context. Please link to quotes you are using.

This quote was an answer to reply #49 in this thread and reply #49 links to outdated User Guide found under -> Top of page -> User Guide -> User Guide.

There was no link to Redrock's "User Guide" post.

I apologize for misrepresenting your quote. But then I don't understand. Why did the person ask about another guide in a guide thread named "User Guide thread for the latest nightlies (Help Needed)"? And why would you give such reply in that very thread? Was it just so that it was/is not complete?

EDIT: Nevermind, I realize that you now are mainly focused on choice nr 1 above. I still think there are presentation issues to be addressed, but everything in its own time. Guess I should create a new thread for my specific purpose.

[Erik Krause]

I transferred the content of the User Guide Thread to the wiki:
https://wiki.magiclantern.fm/playground:camera_help

Would be nice anyone helps improving the text until it is worth to be used as a help file in camera. Currently large parts are still missing. To get write access to the wiki the same credentials as for this forum can be used.

Currently I investigate how the text could be (automatically) converted to RST which eventually could be used in camera. My current favorite is to write a PHP and regex based  simple parser to convert the text. No idea though how this should be triggered ideally. For the other way (RST to wiki) the old technique present as python scripts in the doc folder could perhaps be modified.

[Erik Krause]

Ok, so I have a very coarse parser which converts the Text from https://wiki.magiclantern.fm/playground:camera_help to ReStructured Text files, split by menu. It produces a format much similar to the one in the doc files wich evaluate ok in the Online reStructuredText editor ATM it works only on my local machine. It could be implemented as a dokuwiki plugin or as a stand alone program, depending on what the mechanism would be that will transfers the content to the repository.

It is by no means a complete wikitext parser, but I guess we don't need all bells and whistles. Currently only headlines, list, bold and italics text (RST doesn't support underline) is interpreted. Tables would be nice but will be pretty tedious to do, since RST requires them drawn like ascii art. Images are not yet implemented either. I guess it would be best to hide them in RST comments. This way they won't get lost and could be converted back to wikitext once that way works again, too.

However, all this will only be meaningful if the community updates the text on the wiki. Until now it's only me who did edits. And I think we need good  content before we can ask the devs to either repair the old latex based build system which generates bitmaps as help pages, or implement a new help system, which displays RST directly like the one for the modules.