Let's restore ML help together!Currently, if you press the Info button while in ML menu, you get "Undocumented feature". This shouldn't be the case. Until version 2.3 there where nice help texts. We should restore them for the current releases.
4 years ago Redrocks started the
User Guide thread for the latest nightlies. After a good start it went inactive, probably because the update mechanism was too tedious.
A wiki is much easier to edit. I've transferred the texts from that thread to the ML wiki, which anyone can edit who also can write here, the credentials are the same. The more important part is
camera help the other one
general helpGoalsIn my opinion the first goal should be to provide in-camera help. Have you ever been out in the field without internet access and you didn't get a needed function explained? With internet access it's always possible to find information, but in-camera help is essential and overdue. Later on we can see, if and how we make this a good online user guide.
What can be done by anyone- Go through the text and see whether it would be helpful under the premise that you know little about that function.
- A lot of sections where copied from the help that is already provided on the bottom of the ML screen. This need to be expanded, since there is no point duplicating this information.
- Some sections are not available any more, have moved to a module or where renamed. Those need to be corrected.
- As a first measure mark that sections as INCOMPLETE. How to do this is explained on top of the page. Of course you can also start to improve them right away.
- Look for sections marked as INCOMPLETE and improve them. Remove the INCOMPLETE comment once you're satisfied.
- Don't be afraid to edit something. It's a wiki, your edits will be reviewed and corrected if necessary. You also can add further comments to the section to ask for comment, help or review.
Although the current text is pretty large it's better considered a framework to be filled.
What more is needed?Apart of that I'd like to discuss how we can proceed. Please make this thread sticky instead of the User Guide thread and point to it from various places, namely from
https://www.magiclantern.fm/forum/index.php?topic=12657.0 and from the User Guide thread itself.
I'd also like to discuss the format and the future use. Once it is more up to date it should be used f.e. as a target on the
feature matrix, which currently still uses the 2.3 user guide.
I have some experimental PHP code that splits the wiki article into files, one for each main menu point, and converts the content to RST format, much like the old menu text files in the /doc/ folder on bitbucket. This code could be turned into a dokuwiki plugin which writes those files on any save, but other uses are also possible.
I like Alex' proposal to
embed the help texts in the source code in order to have them up to date more likely, for which a text only format would be probably better. In the end there should be a two-way exchange: The wiki text should update the embedded help and vice versa. There is already some python code in the /doc/ folder on bitbucket that can convert RST to dokuwiki text, so that way should be possible too. Someone familiar with bitbucket could certainly automate both import and export.
And last but not least many agreements are necessary to have a uniform help file. F.e. the menu topics that are added by modules are listed under the respective menu but should be marked clearly as such.
A lot of work to do, but for a healthy community like this one it should be doable. What do you think?
