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

Walter Schulz

  • Hero Member
  • *****
  • Posts: 5713
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

bpv5P

  • Member
  • ***
  • Posts: 116
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

  • Hero Member
  • *****
  • Posts: 5713
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) ...

Danne

  • Hero Member
  • *****
  • Posts: 3390
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

  • 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: 62
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: 51
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: 3406
  • 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: 3406
  • 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

  • Hero Member
  • *****
  • Posts: 5713
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.

Audionut

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 3406
  • 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

  • Senior
  • ****
  • Posts: 455
  • 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: 10326
  • 5D Mark Free
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

  • Senior
  • ****
  • Posts: 455
  • 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: 3406
  • 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

  • Hero Member
  • *****
  • Posts: 5713
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 ...

kichetof

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