Another approach for ML tutorials and help files?

[Walter Schulz]

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]

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]

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]

Personally, lack of time. Seems like a good project. By the way. Can´t get acces to your bitbucket links.

[tecgen]

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

[canneloni]

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?

[JohanJ]

@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

[Audionut]

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]

Walter, I forgot to say thanks for taking on this massive task.

Feel free to PM as needed.

[Walter Schulz]

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]

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]

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]

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]

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]

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]

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]

First attempt

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

Need some works

edit: for the moment, I don't see how to get menu parent items from block like this:
https://bitbucket.org/hudson/magic-lantern/src/30db46575511dc13093c1557ea00b92184264ab7/src/af_patterns.c?at=unified&fileviewer=file-view-default#af_patterns.c-385
https://bitbucket.org/hudson/magic-lantern/src/30db46575511dc13093c1557ea00b92184264ab7/src/zebra.c?at=unified&fileviewer=file-view-default#zebra.c-2676

I only need .name from parents, not inside .children. If you know how to parse that, generator will do the job!

[kichetof]

Done  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]

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]

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]

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.

[DeafEyeJedi]

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

That would be wonderful!

[kichetof]

taking a look at this

Done. Look at this

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

[Walter Schulz]

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

[Audionut]

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.