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

Walter Schulz

  • Hero Member
  • *****
  • Posts: 5646
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: 102
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: 5646
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: 3249
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: 51
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

  • New to the forum
  • *
  • Posts: 47
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