Putting the ‘You’ in Documentation

First things first, sorry about that title. But once I had thought of it I couldn’t back out.

Now then. In a previous blog I described the new documentation format that we would be using for the dictionary in LiveCode 8, which aimed to be much more easily read and modified than the old XML files. Indeed, there have been more documentation bugs fixed in the 8.0 cycle than those of 6.7 and 7.1 put together, so on that front it has already been reasonably successful.

We have had some community contributions to the documentation, but we would love to have more. So to that end I’ve put together a guide outlining our documentation goals and a step-by-step guide to making changes. The guide takes you through how to modify the appropriate files and submit a pull request in three different ways – using only the GitHub website, using a downloaded Git GUI client, and using the command line.

It really is easy to do. To prove it, I asked our Digital Marketing Manager Steven, who had absolutely no experience with using GitHub before, to fix bug 14837 using the guide.

“Hey Steven, can you correct the function error in the documentation – find it, fix it, commit it via GitHub, oh and it’s do-able in 15 mins.”

Several of these words seemed foreign to me, GitHub that’s the dev tool thing right? It must be complicated. I signed up to GitHub, navigated to the GitHub web interface instructions which perfectly guided me through making the change. It was straightforward and to this day i still brag about my GitHub contribution. If you are like me and thought contributing to LiveCode via GitHub was just for the advanced guys, you would be wrong. Spot the error or identify a missing example, follow the guide, fix and commit the change, feel great about it.

So even if you have never used GitHub before, please don’t feel daunted! By giving this a go, you will be contributing directly to improving the docs of LiveCode. You will also gain some Git knowhow, if you don’t have some already, which could be beneficial to other projects you are involved with. And maybe you will start to eye up some personal IDE bugbears with a view to submitting your own fix.

Dictionary

As described in the contributing document above, one of the best ways to contribute to the dictionary is to add or correct examples. Ideally every example would be completely self-contained, so that it can be copied from the docs and immediately used to demonstrate functionality.

Another good place to start if you’re looking to dip your toes into the sea of GitHub (it’s warmer than it looks!) is to look at mismatches between parameter names in the entry’s syntax and in the parameter’s description below.

For example, at the time of writing there is a parameter named defaultAnswer in the ask password syntax, but the corresponding description is for a parameter named defaultResponse. So here is a pull request that fixes the issue.

When your pull request is reviewed, the reviewer may add some comments with any issues with the pull request, or any suggested changes. So make sure you check back on your pull request periodically (or have email notifications on)!

A satisfied reviewer will add a rather cryptic-looking comment of the form

@livecode-vulcan review ok a40093f

(as Peter has in the first commment of the above pull request). This tells our most dedicated employee, vulcanbot, who works round the clock and almost never takes a holiday, that the pull request is ok. Vulcanbot will dutifully go off and trigger test builds on all the platforms to make sure the changes haven’t broken anything. Although if the changes are just to docs files, this is very unlikely to be the case!

When the LiveCode 8 installers are built, the script that parses the docs files spits out warnings when there is a parameter name mismatch like the one I fixed above – so here is a list of similar outstanding issues should you wish to begin with a small fix.

There is also a dedicated category in our bug tracker for documentation bugs. Note if you fix one of these we will also ask you to submit a bugfix note for our release notes. The process for this is also described in the contributing to docs document. Steven’s docs fix is a good example of a fix requiring a bugfix note.

Guides

Elanor has written previously about the process of converting the user guide to markdown format. Doing this made it possible for us to add the guide to our GitHub repository and accept contributions to it. As of 8.0 DP 13, the user guide has been split up into several smaller guides, and the directory structure has been rejigged so that they are properly browsable on GitHub. They have also been categorised as IDE guides and engine guides, depending on what code changes are most likely to affect them. This will make it easier to enforce guide changes along with code changes, which will therefore help keep our guides up to date. The guides are incorporated into LiveCode 8.0 releases automatically, so any changes that are merged will be available in a live version shortly afterward.

Community Docs Managers

We will review docs pull requests and merge them into main repository. If the docs traffic is relatively quiet, it should be easy for us to keep on top of the reviewing. But hopefully this will not be the case. Being overwhelmed with documentation updates from the community is a problem well worth having! If we find ourselves in this situation, we would like to appoint some volunteers to oversee the review process. If this sounds like something you would like to do, feel free to note your interest in the comments.

Previewing Docs

I have written a very primitive docs previewer to help view the results of docs changes. Note it is detached from the LiveCode Script dictionary, so links will appear as plain text for now.