Another approach for ML tutorials and help files?

Started by Walter Schulz, September 04, 2017, 10:16:23 PM

Previous topic - Next topic

0 Members and 1 Guest are viewing this topic.

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

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

@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

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)

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

Quote from: a1ex on October 10, 2017, 10:42:11 AM
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

Quote from: a1ex on October 10, 2017, 10:42:11 AM
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.




Quote from: kichetof on October 10, 2017, 01:33:51 PM
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

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

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

Quote from: Audionut on November 18, 2017, 07:19:21 AM
Needs further navigation to extended information.

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


.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.
EOS RP, 5dIII.113/Batt.grip, 5dIII.123, 700d/Batt.Grip/VF4 viewfinder + a truckload of new and older Canon L, Sigma and Tamron glass

DeafEyeJedi

5D3.113 | 5D3.123 | EOSM.203 | 7D.203 | 70D.112 | 100D.101 | EOSM2.* | 50D.109

kichetof

Quote from: Audionut on November 18, 2017, 07:19:21 AM
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

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

Audionut

Quote from: kichetof on November 22, 2017, 09:46:01 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.

Quote from: Walter Schulz 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.

The ball is rolling.  ;)