Volunteer github guru for documentation submissions?

[Devin Asay]

> On Apr 13, 2016, at 11:52 AM, J. Landman Gay <jacque at hyperactivesw.com> wrote:
> 
> On April 13, 2016 7:58:21 AM Mike Kerner <MikeKerner at roadrunner.com> wrote:
> 
>> I'm done.  I have better things to do than fight through trying to help
>> everybody by making the docs better.
> 
> I can so sympathize, but at least I don't feel so stupid now. I am going to keep plugging away at it, doing only the most minimal changes until I know what I'm doing. I plan to do only one or two a day to keep down the frustration. Last night I forgot to add labels to my descriptive summaries and when I tried to go back to do that I could find no way to edit them. Peter put them in for me so there must be a way but it sure isn't obvious.

I sympathize, too, but after a few days of intensively trying to figure this out (and probably causing Ali and Peter some head-shaking), it’s starting to make sense. When I start into editing a dictionary entry now this is my process:

1 - Find the entry I want to work on by identifying errors or omissions in the LC Dictionary.

2 - Make extra, extra sure I go in at https://github.com/livecode/livecode/tree/community-docs/docs/dictionary. I really fouled this up my first couple of pull requests.

3 - Navigate to the category the dictionary entry belongs in; e.g. keyword, property, command, etc. and open the specific document.

4 - Once the doc is open hit the Edit button.

Once we’re at this point, I think a couple of tools could really make things easier:

- A style guide. When do you use block quoting? How thorough should we be at linking terms within the document and adding entries to the References: section? When to use a list? How and when do you create tables anyway?

- A markdown validator. Even though markdown is way simpler than something like html, it’s easy to miss things. (@peter-b, can something like this be done in Atom?)

- A markdown previewer. I know Ali made a stab at this, but I wasn't able to get it to work.

5 - I’ve found that once I get to this point, it’s straightforward to submit the pull request. Well, except that you have to Click about three times on different buttons before it’s really, really submitted. 

Finally, I think this effort could benefit by having a “traffic cop” who monitors documentation problems and invites people to fix them. No, I don’t want to be that guy. :)

These are mainly just musings on this process after a few days of deep diving into it. Fiddly but doable.

Devin



Devin Asay
Office of Digital Humanities
Brigham Young University