Author Topic: Another approach for ML tutorials and help files?  (Read 11829 times)

Walter Schulz

  • Contributor
  • Hero Member
  • *****
  • Posts: 7003
Another approach for ML tutorials and help files?
« on: September 04, 2017, 10:16:23 PM »
Hello, out there!

You may have wondered what I'm up to with those postings:
http://www.magiclantern.fm/forum/index.php?topic=20451.msg189627;topicseen#msg189627
http://www.magiclantern.fm/forum/index.php?topic=20454.msg189640;topicseen#msg189640

Sorry (kind of), TL;DR follows now.
For long time readers it may not come as a surprise: I'm not exactly a friend to sloppy and outdated tutorials (video and text) spread all over the place. ML gives the community wonderful enhancements for free but there is something to be desired concerning documentation. Progress on help texts seems to be stalled. And dreaming of something like "ML 101" - and keeping it up-to-date with devs constantly pushing cam's abilities to unknown shores ...
Audionut put effort in collecting help text but using forum posts doesn't look promising to me in terms of long time support.
How to get out of this mess?
Well, devs have tools for collaborative work and peer reviews. I think it's far from perfect suited for this need but it is there and - I hope - it's useable for non-devs.

That's what I did:
1) Put up a topic I wanted to write about a long time (but doesn't interfere with help text content) and put it into a forum post (using bbcode bells and whistles Audionut pointed me to. Not necessary but making navigation in long posts much easier). THat's the german one.
2) Transfered the "code" to my Bitbucket repository https://bitbucket.org/WalterSchulz/walter_ml_tut/src/799b197966858abc18afa15f449cf65801018afb/HHOG/de/?at=default -> Posting
3) Used http://deepl.com/translator to auto-translate (yes, with most obvious errors) to create https://bitbucket.org/WalterSchulz/walter_ml_tut/src/799b197966858abc18afa15f449cf65801018afb/HHOG/en/?at=default -> Auto-Translate
4) Transfered contents to second forum post (the germish/autotranslate one)

What to do now? Master plan:
-> Find someone (or more people) willing to translate "germish/autotranslate" using Bitbucket branching and pull requests to get a version not so germish. And maybe some suggestions concerning layout, structure, contents ....
-> (If available) ask for peer review.
-> Declare "english" version to be fresh and to be "master document". All further changes will take place in this document first.
-> Transfer content to forum post (replacing previous post).
-> Transfer changes to german document
-> Ask for translators willing to transfer document into other languages.

What do you think? Too much? Too complicated? Too little? Wrong approach? Sounds good, doesn't work ... forget that, please ...


PS: If you want horsing around with bbcode and stuff: I'm running SMF inside a virtual machine. Just download VM file from Bitnami, change database (via web interface in v14) to UTF-8 and Bob is your uncle. https://bitnami.com/stack/simple-machines-forum
Photogs and videographers: Assist in proof reading upcoming in-camera help!. Your input is wanted and needed!

bpv5P

  • Member
  • ***
  • Posts: 167
Re: Another approach for ML tutorials and help files?
« Reply #1 on: September 05, 2017, 04:47:02 AM »
My opinion: you should do standard man pages using mandoc. Mandoc can translate to other codes, so it's simple to convert to HTML or PDF.

I can help wriiting most of the documentation of the features, but not on the technical (code) knowledge.
Documentation requires a big effort to maintain updated. If we are going to start it, we should maintain it. Else, don't even start.

Walter Schulz

  • Contributor
  • Hero Member
  • *****
  • Posts: 7003
Re: Another approach for ML tutorials and help files?
« Reply #2 on: September 12, 2017, 09:37:20 AM »
Don't want to sound like a loser but I'm curious about "The Usual Suspects" keeping radio silence about the subject. Did I piss off the party?


EDIT: Permissions fixed (I hope) ...
Photogs and videographers: Assist in proof reading upcoming in-camera help!. Your input is wanted and needed!

Danne

  • Contributor
  • Hero Member
  • *****
  • Posts: 6212
Re: Another approach for ML tutorials and help files?
« Reply #3 on: September 12, 2017, 10:02:21 AM »
Personally, lack of time. Seems like a good project. By the way. Can´t get acces to your bitbucket links.

tecgen

  • Contributor
  • Freshman
  • *****
  • Posts: 53
Re: Another approach for ML tutorials and help files?
« Reply #4 on: September 12, 2017, 11:27:05 AM »
Since Magic Lantern is using Bitbucket from Attlasian to host the whole open source project, why not simply using Confluence from Attlasian as well? Within Confluence you are able to write text and technical documentation very easy.

https://www.atlassian.com/software/confluence
https://www.atlassian.com/software/views/open-source-license-request
Canon 5D Mark II, 50D, 550D/Rebel T2i, EF 40mm f/2.8 STM, Sigma 18-35mm f/1.8, EF 85 f1.8, EF 135 f2.8 SF, Zoom H2n

canneloni

  • Freshman
  • **
  • Posts: 96
Re: Another approach for ML tutorials and help files?
« Reply #5 on: September 12, 2017, 12:14:26 PM »
I would love to help on the documentation and translation but i cant access your bitbucket links. And another Question: Why not use a normal wiki?
100D.100B ; Canon 18-55 STM ; Canon 50 1,8 II ; Canon 75-300 4,0 - 5,6 III ; Sigma 17-50 2,8

JohanJ

  • Freshman
  • **
  • Posts: 88
Re: Another approach for ML tutorials and help files?
« Reply #6 on: September 12, 2017, 08:40:13 PM »
@Walter. Your approach is really appreciated. Automating translations would reach many more people and lower the threshold for active contribution.
Personally I would prefer a WIKI like platform. Forum threats are built for discussions and that  makes it often difficult to  keep  "first post" up to date. So how about combining both methods (even though I have no clue how auto translated wiki should work in a consistent way, as manual alternations could be done in any  of the provided languages)

Sent from my SM-G930F using Tapatalk

60D.111 / 100D.101 / M2.103

Audionut

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 3583
  • Blunt and to the point
Re: Another approach for ML tutorials and help files?
« Reply #7 on: October 04, 2017, 08:04:40 AM »
Life is smashing me to pieces atm.  Don't wait for me, progress ahead.

I notice the wiki "wiki.magiclantern.fm" has been getting updates.
My suggestion, new wiki link "updated user guide (WIP)".  With edit permissions granted as you guys see fit.  Copy paste should get bulk of data transferred. 

Feel free to add me, it would be nice to contribute even if it's only once in a blue moon for the foreseeable future.

Audionut

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 3583
  • Blunt and to the point
Re: Another approach for ML tutorials and help files?
« Reply #8 on: October 09, 2017, 06:17:13 AM »
Walter, I forgot to say thanks for taking on this massive task.

Feel free to PM as needed.

Walter Schulz

  • Contributor
  • Hero Member
  • *****
  • Posts: 7003
Re: Another approach for ML tutorials and help files?
« Reply #9 on: October 09, 2017, 03:52:16 PM »
Thanks but haven't done that much yet and - at the moment - not doing anything. Limbo. Decision needed which way to go now. HIC SVNT LEONES.
Photogs and videographers: Assist in proof reading upcoming in-camera help!. Your input is wanted and needed!

Audionut

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 3583
  • Blunt and to the point
Re: Another approach for ML tutorials and help files?
« Reply #10 on: October 10, 2017, 02:29:08 AM »
Maybe I'm wrong, but I got the impression that a1ex is happy to leave it up to the community to get this done.  I was always of the opinion that it should rest on community, because developers should be locked away in their basements, coding, safe from dragons.

I'm positive a1ex once mentioned that the data just needs to be compiled, somewhere (anywhere), and he can use his magical skills to transfer the content to the appropriate places (in camera for example).  The more I think about it, the more I like bitbucket, since lots of people who contribute to the project already have everything needed to contribute to this specific part of the project.  You don't need to wait for anything.  Fork, contribute, push.

I think we should focus entirely on the English version (at least for the time being), since it will have a larger contribution to the project.  I think it's far to early to ask for translators, because translator walks through door, sees a pig sty, turns around and leaves.  We should invite people over after the house has been cleaned.

kichetof

  • Contributor
  • Senior
  • *****
  • Posts: 469
  • Take a beer and enjoy it!
Re: Another approach for ML tutorials and help files?
« Reply #11 on: October 10, 2017, 09:50:10 AM »
What do you think about something like that:

One repo or branch inside ML, with a structure like ML menus on cam (with an example it'll be more understandable :) ) and wrote in markdown syntax or plain text.


Help (folder)
  • Sound (folder)
    • Analog gain.md
    • Digital gain.md
    • ..
  • Expo (folder)
    • White balance.md
    • ISO.md
    • ..
  • Overlay (folder)
    • Global Draw.md
    • Zebra.md
    • ..
  • Movie (folder)
    • Bit Rate (CBR).md
    • REC key.md
    • ..
  • Shoot (folder)
    • Advanced Bracket.md
    • Intervalometer.md
    • ..
  • Focus (folder)
    • Trap Focus.md
    • Follow Focus.md
    • ..
  • Display (folder)
    • LV brightness.md
    • LV contrast.md
    • ..

Inside each markdown files, we could add the compatibility for each CAM. Exemple: works on: 5D2,5D3,40D,.. (goal: add the possibility to filter the help by cam)

On a help page from magiclantern.fm, we could parse (php, js, python) the markdown inside a static page:

Tab/section/accordion: Sound
https://api.bitbucket.org/1.0/repositories/hudson/magic-lantern/raw/default/help/sound/Analog gain.md
                                                                                                        ^       ^      ^       ^
                                                                                                    branch    |       |        |
                                                                                                          help folder |        |
                                                                                                                     ML Menu  |
                                                                                                                              specific help

With this structure, it's possible to have a help for any branches
Maybe a script could generate the whole structure (folder/md files)

It's my idea of the day  ;)

a1ex

  • Administrator
  • Hero Member
  • *****
  • Posts: 12353
  • Emergencies only
Re: Another approach for ML tutorials and help files?
« Reply #12 on: October 10, 2017, 10:42:11 AM »
Previous ML docs used reStructuredText rather than Markdown - similar concept. The QEMU guide uses it, for example. Another example - old FAQ (this one shows up as plain text; if renamed, Bitbucket will render it nicely).

This file structure looks nice, with only one nitpick: it's not in the same place as the source code. Currently, the two help strings are pretty much up to date, while the RST docs (stored as one file per menu, but in a different directory) are not.

What about storing both versions (menu-like directory structure vs embedded in source code) and syncing from both places? That is, whenever one of these two copies gets updated, the other one is auto-updated by some scripts.

Back then, I used to edit the RST docs and compile 3 versions: MediaWiki, regular PDF and in-camera PDF (converted to pre-rendered bitmaps).
I was trying to do this kind of bidirectional sync with the wiki, manually (to sync my changes from RST with user contributions from wiki). It wasn't funny - because of the different syntax between wiki and RST. If the two sources use the same language, it shouldn't be difficult.

DokuWiki also has RST and Markdown plugins - in this case, we could just sync between all the 3 copies. Or maybe stick with 2 copies - inline docs and DokuWiki pages with RST or MD syntax. Once this sync is working and the wiki docs are up to date, I hope there will be a higher incentive for other users to contribute.

Camera compatibility tags can be automated (either by preprocessing/parsing the source code, or by exporting the menu structure for each camera model from QEMU).

kichetof

  • Contributor
  • Senior
  • *****
  • Posts: 469
  • Take a beer and enjoy it!
Re: Another approach for ML tutorials and help files?
« Reply #13 on: October 10, 2017, 01:33:51 PM »
Added language
https://api.bitbucket.org/1.0/repositories/hudson/magic-lantern/raw/default/help/en/sound/Analog gain.md
                                                                                                        ^       ^   ^   ^       ^
                                                                                                    branch    |    |    |        |
                                                                                                      help folder  |    |        |
                                                                                                            languages  |        |
                                                                                                                     ML Menu    |
                                                                                                                              specific help

it's not in the same place as the source code.
Yes, two visions: one from developper: it's more easy to keep doc up to date to update comments in same place; second one from contributor: where's the doc files to update ? inside the code ? Difficult to see everything between every files/lines

What about storing both versions (menu-like directory structure vs embedded in source code) and syncing from both places? That is, whenever one of these two copies gets updated, the other one is auto-updated by some scripts.

I like this idea! Developper updates the doc inside source --> Doc updated; Contributor updates the doc inside help folder --> Source code updated. Cross update may be the solution to keep doc up to date in every plateform.

Audionut

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 3583
  • Blunt and to the point
Re: Another approach for ML tutorials and help files?
« Reply #14 on: October 11, 2017, 06:12:10 AM »
This discussion is quickly exceeding my pay grade.  Change of mind, to make things simple I propose new easy to maintain user guide.

Page 1.  User manual, lol, ML is for power users you dummy.

END.



I like this idea! Developper updates the doc inside source --> Doc updated; Contributor updates the doc inside help folder --> Source code updated. Cross update may be the solution to keep doc up to date in every plateform.

I understand this and agree.

I have enough spare brain cells to copy paste, speeeling, minor updates and such, but (helping) setting up the back end............

Walter Schulz

  • Contributor
  • Hero Member
  • *****
  • Posts: 7003
Re: Another approach for ML tutorials and help files?
« Reply #15 on: October 14, 2017, 09:37:37 AM »
Before it slips under the horizon: May I ask kichetof or a1ex to create an example in bitbucket for this file structure you have in mind? Call it a teaser ...
Photogs and videographers: Assist in proof reading upcoming in-camera help!. Your input is wanted and needed!

kichetof

  • Contributor
  • Senior
  • *****
  • Posts: 469
  • Take a beer and enjoy it!

kichetof

  • Contributor
  • Senior
  • *****
  • Posts: 469
  • Take a beer and enjoy it!
Re: Another approach for ML tutorials and help files?
« Reply #17 on: November 01, 2017, 09:59:06 PM »
Done  8) think different, acts simply.

Parser is now written in python and does what I expected. What do you think ?

https://bitbucket.org/kichetof/magic-lantern/src/7f853a28906fd9e57ddc3bee703382f229f556c7/help/?at=help_files

(Maybe some bugs with modules who enhances some menu/submenu)

Audionut

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 3583
  • Blunt and to the point
Re: Another approach for ML tutorials and help files?
« Reply #18 on: November 18, 2017, 07:19:21 AM »
The navigation is ok, atleast it's ordered similar to the ML menu.

Needs further navigation to extended information.

For instance, taking a look at this, some sort of navigation from 'Silent Mode' that leads to further explanation of the available options.  All of the bold entries need expansion.

I guess by linking to this further information, the current implementation can be transferred to and fro the cameras, with extended information being parsed, and only available via www.

kichetof

  • Contributor
  • Senior
  • *****
  • Posts: 469
  • Take a beer and enjoy it!
Re: Another approach for ML tutorials and help files?
« Reply #19 on: November 18, 2017, 10:07:19 AM »
Needs further navigation to extended information.

Yes, the parser need some enhancements to extract multi-lines. Add .choices options could also be added

Code: [Select]
.choices = CHOICES(
    "Simple",
    "Burst",
    "Burst, End Trigger",
    "Best Focus",
    "Slit-Scan",
    "Full-res",
),
.help = "Choose the silent picture mode:",
.help2 =
    "Take a silent picture when you press the shutter halfway.\n"
    "Take pictures until memory gets full, then save to card.\n"
    "Take pictures continuously, save the last few pics to card.\n"
    "Take pictures continuously, save the images with best focus.\n"
    "Distorted pictures for funky effects.\n"
    "Experimental full-resolution pictures.\n",

If it could be useful, I'll spend some time to enhance it :)

axelcine

  • Member
  • ***
  • Posts: 216
  • Hi, I'm Axel, editor, journalist and photographer
Re: Another approach for ML tutorials and help files?
« Reply #20 on: November 18, 2017, 06:45:43 PM »
Walter, I'm sorry that this post came to my attention so late - my photo school and a rather large project ate up a lot of time. But I'm Danish - a neighbor to Germany, and I speak German. I have always enjoyed your dry wit and very precise comments, so I suppose, your command of English is top notch. But if you'd want a helping hand in translation, I'd be proud to give it a try.
5dIII.113/Batt.grip, 5dIII.123, 700d/Batt.Grip/VF4 viewfinder, 760d + a truckload of new and older Canon, Sigma and Tamron glass

DeafEyeJedi

  • Hero Member
  • *****
  • Posts: 3366
  • 5D3 | M1 | 7D | 70D | SL1 | M2 | 50D
Re: Another approach for ML tutorials and help files?
« Reply #21 on: November 18, 2017, 11:02:31 PM »
If it could be useful, I'll spend some time to enhance it :)

That would be wonderful!
5D3.113 | 5D3.123 | EOSM.203 | 7D.203 | 70D.112 | 100D.101 | EOSM2.* | 50D.109

kichetof

  • Contributor
  • Senior
  • *****
  • Posts: 469
  • Take a beer and enjoy it!
Re: Another approach for ML tutorials and help files?
« Reply #22 on: November 22, 2017, 09:46:01 PM »
taking a look at this

Done. Look at this :)

New way to parse source files (4x faster: 1s vs 4s). (hectic brainstorm  :o)

Walter Schulz

  • Contributor
  • Hero Member
  • *****
  • Posts: 7003
Re: Another approach for ML tutorials and help files?
« Reply #23 on: November 22, 2017, 09:48:56 PM »
Just want to note I'm occupied with other tasks right now but will be back on this ASAP.
Photogs and videographers: Assist in proof reading upcoming in-camera help!. Your input is wanted and needed!

Audionut

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 3583
  • Blunt and to the point
Re: Another approach for ML tutorials and help files?
« Reply #24 on: November 23, 2017, 12:28:06 PM »
Done


Nice work.

Can you add links to the bold headings?
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.

Just want to note I'm occupied with other tasks right now but will be back on this ASAP.

The ball is rolling.  ;)

kichetof

  • Contributor
  • Senior
  • *****
  • Posts: 469
  • Take a beer and enjoy it!
Re: Another approach for ML tutorials and help files?
« Reply #25 on: November 23, 2017, 07:14:17 PM »
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

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 3583
  • Blunt and to the point
Re: Another approach for ML tutorials and help files?
« Reply #26 on: November 24, 2017, 05:46:43 AM »
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

  • Contributor
  • Senior
  • *****
  • Posts: 469
  • Take a beer and enjoy it!
Re: Another approach for ML tutorials and help files?
« Reply #27 on: November 24, 2017, 06:33:09 PM »
Yeah we’re on the same way  8)
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

  • New to the forum
  • *
  • Posts: 14
Re: Another approach for ML tutorials and help files?
« Reply #28 on: January 08, 2018, 05:26:14 PM »
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.
5D3 User. Lexar Card 2000x 300 MB/s. Komputabay  1000x 32GB. Fr: 1.2.3.

Walter Schulz

  • Contributor
  • Hero Member
  • *****
  • Posts: 7003
Re: Another approach for ML tutorials and help files?
« Reply #29 on: January 09, 2018, 06:41:49 PM »
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.
Photogs and videographers: Assist in proof reading upcoming in-camera help!. Your input is wanted and needed!

Erik Krause

  • Freshman
  • **
  • Posts: 59
Re: Another approach for ML tutorials and help files?
« Reply #30 on: May 14, 2018, 06:25:58 PM »
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

  • Contributor
  • Hero Member
  • *****
  • Posts: 7003
Re: Another approach for ML tutorials and help files?
« Reply #31 on: May 14, 2018, 07:51:17 PM »
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.
Photogs and videographers: Assist in proof reading upcoming in-camera help!. Your input is wanted and needed!

Tullen

  • Freshman
  • **
  • Posts: 59
Re: Another approach for ML tutorials and help files?
« Reply #32 on: May 15, 2018, 06:34:40 PM »
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

  • Freshman
  • **
  • Posts: 59
Re: Another approach for ML tutorials and help files?
« Reply #33 on: May 15, 2018, 10:45:52 PM »
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

  • Freshman
  • **
  • Posts: 59
Re: Another approach for ML tutorials and help files?
« Reply #34 on: May 16, 2018, 01:09:28 PM »
Is there more relevant material other than Redrocks guide and the pages with features, builds etc https://builds.magiclantern.fm/index.html?

Tullen

  • Freshman
  • **
  • Posts: 59
Re: Another approach for ML tutorials and help files?
« Reply #35 on: May 16, 2018, 07:08:08 PM »
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

  • Contributor
  • Hero Member
  • *****
  • Posts: 7003
Re: Another approach for ML tutorials and help files?
« Reply #36 on: May 16, 2018, 07:24:49 PM »
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.

Photogs and videographers: Assist in proof reading upcoming in-camera help!. Your input is wanted and needed!

Erik Krause

  • Freshman
  • **
  • Posts: 59
Re: Another approach for ML tutorials and help files?
« Reply #37 on: May 16, 2018, 08:46:34 PM »
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

  • Freshman
  • **
  • Posts: 59
Re: Another approach for ML tutorials and help files?
« Reply #38 on: May 17, 2018, 12:08:51 AM »
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

  • Freshman
  • **
  • Posts: 59
Re: Another approach for ML tutorials and help files?
« Reply #39 on: May 26, 2018, 11:12:26 PM »
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

  • Freshman
  • **
  • Posts: 59
Re: Another approach for ML tutorials and help files?
« Reply #40 on: May 28, 2018, 09:01:10 PM »
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.