I received some feedback from a contributor who wanted to contribute to the docs, and I wanted to share some of what they went through and propose some solutions to make it easier for the next person.
I already had gitbash installed and have used it for other API stuff previously however didn't realize this was out of date so installed the latest version.
Similarly I already had python 2.7 installed which may have caused me a few problems early on but updated this to the latest version. (and uninstalled the old version)
I installed Github Desktop and downloaded a local copy of odk-docs through this. However in some other messing around with python I must have decided it made more sense to clone through git rather than use Github Desktop; so I haven't continued using this.
In general it was a little difficult to determine which code to follow when using Windows + Bash, rather than Linux or Macs etc. Generally if one suggestion didn't work I tried the other. Also a bit confused sometimes whether the '$' should be included or is that just there for illustration? Again, complete noob!
The instructions to check if you have python and virtualenv installed are tricky as you are typing something in and hope that you see nothing - rather than seeing a confirmation or something. Appreciate this may just be the way things are. "If you get an error, you PROBABLY don't have it"
Also in some of the text it refers to using python3 whereas in my setup I think I just have this as python.
I am not 100% sure how Github branches relate to desktop folders (or if they do at all). In gitbash I can see odk/docs in yellow and then in the branch (test) in blue. I assume when changes are pushed back to the main source the branch shows what issue you have been working on.
Installed GLFS, fairly simple, though not 100% if I needed to at this point
I skipped the Android Tools/Studio steps (again not sure if this is needed)
I installed Atom as one of the recommendations, this was fairly simple. I wondered if Notepad++ was similar as I already had that installed but I can see they do a similar job at a base level. Though Atom seems more advanced/user friendly.
So I had succesfully cloned odk-docs locally and was editing this in Atom. I made a dummy page (test.rst) with some placeholder text to see if I could load this up. Saved file.
Had to install sphinx which by this point I figured out myself but not sure this is explicitly mentioned in the docs.
I couldn't seem to run the spelling or style checks which seemed to be necessary before build-odk in order to locally view what changes you had made.
Sometimes src is referred to. I assumed this meant odk1-src or odk2-src depending on the bit you are supposed to be working on?
So "sphinx-build -b dirhtml src build" is about where I decided to call it a day. I was getting "configuration error: there is a programmable error in your config file" responses followed by tracebacks that I really did not understand and really didn't know what to do from here.
I investigated an additional package for Atom called 'sphinx-preview' which I thought might allow me to at least see what my .rst file would look like but didn't manage to get this working. (Needs Docker? and Win10 professional?) However I could paste the code into at rst.ninjs.org to see something (obv doesn't work with all the style / links that are built in natively)
If it's relevant I was also using Windows 10 and Firefox. I do appreciate the warning at the start of the guide that Windows is not the default choice. Of the Windows options not sure if the Linux subsystem preferred over using gitbash? Or if there is no real difference.
This was very painful feedback for me to read. I'm always so optimistic that folks will be able to get started and it's now clear that the bar is way too high for docs and it might take hours to get to a first contribution.
I think we need to take a step back and rethink our approach to getting normal humans (e.g., not programmers ) to contribute to docs. I'm thinking something like this would probably have resulted in a better experience...
In the readme, we lead with the fact that these are docs as code and it could be a little bumpy.
We recommend people first file an issue with what they want to fix/contribute.
We recommend people start by writing the content in a Google Doc or whatever first and attach it to the issue for review first.
Once the content is ready, then if folks want, they can try to get the whole git/sphinx/python build thing working. And maybe we lead with telling them to use the Edit in GitHub button. Or provide a VM or web service or something turnkey for them to use.
Have others who have tried to contribute to docs had problems? Do the above steps seem like reasonable improvements? Any other ideas on how we could lower the bar?
This sounds like a good area for me to focus on during Doc Sprints next week.
I think part of the problem is that I didn't (And still don't) have a Windows machine to work through the procedures and refine instructions. Volunteers who use Windows would be very appreciated. (I'll try to rustle up some people on Monday.)
Thanks for volunteering to do this, @adammichaelwood. Very excited to see the improvements you come up with!
If you can't find Windows volunteers, one way to get the Windows experience is to use these free virtual machines from Microsoft. The VMs are nice cause then you can snapshot the process so you can go back and retry things in a clean environment.
Given VMs, could you offer a pre built VM or perhaps a pre built image that can be run on a usb stick that none programmers could use? Something that will boot, have the environment installed that people could then just use. A little like the pre built environment for Aggregate?
I've thought about that. I've also thought about containerizing the docs writing environment.
I'm not opposed to someone tackling that. My worry is that it would not make things simpler enough.
I've worked with Sphinx only in two projects, so I'm not the most experienced user. Also not very active on ODK's docs, but I can relate to the original post's comments.
I agree that not having to set a dev environment would be great. I believe that one can use GitHub to edit a file and do simple sanity checks (GitHub renders .rst files). Then, every PR gets build by CircleCI (takes 8 mins), which lets the doc editor review the final HTML/PDF available in the artifacts tab.
Other than that, I like the idea of Dockerizing all the tooling required to check and build the docs. Although this reduces the onboarding effort, it also introduces yet another tool to the stack.
Since the docs workflow doesn't require so many processes, we could wrap them into a high-level tool which would be the only one the users would have to learn and deal with. This tool could be implemented inside the Docker image, using whatever technology we would see fit, going from bash scripts to any other task-oriented tool. This tool would be the entrypoint of the Docker image, which would make things even easier for the doc editors.
What concerns me about Dockerizing the environment is that it won't actually make things easier, just shift the complexity. So instead of telling a contributor to do three or four steps, we start with "Install Docker". I don't know that this would make it more likely to get non-techie contributors.
I agree that Docker, by itself, it doesn't solve anything.
My point was that it's key to provide a unique tool for every step of the workflow. Docker enables us to provide such unique tool, safe from variations in underlying tools as python, sphinx, etc., in the sense that we can control our tool's commands and args, and provide precise documentation and examples, but we can't do the same with third-party tools.
So, a solution to the problem we're exploring could be composed of a Docker image that includes a tool (the entrypoint) developed by us. Our users would only require Docker to be ready to work with the docs. We can argue that users still need to install Docker, but I think that it's a huge improvement regarding the current situation. Installing Docker nowadays can be a double-click process.
Another more disruptive option would be to migrate the docs to a tool like https://github.com/netlify/netlify-cms, which is completely integrated into the git workflow. This one lets you edit docs in place or use a WYSIWYG CMS that gets deployed alongside the webpage. Netlify has a full featured free tier for OSS projects.
With hindsight, I agree that Dockerization just shifts the complexity onto others and doesn't much reduce the barrier to engagement.
For a drive by editor it needs to be simple, preferably without installing anything and using tools they are familiar with.
I guess key to this is not just the tooling but the workflow and role definition.
Ideally there would be a stepped approach to contributing - if this is my first contribution. I probably need just enough info on standards in order to contribute at a low level, rather than having to imbibe the complete set of standards (which may put me off as much as the tech side of things). Also as a newbie the workflow needs a higher level of checking perhaps than a seasoned contributor.
Do you need to expose the gubbins to the entry level contributor?
If the editor/moderator and contributor roles are fully split, could you simply use Google/Microsoft workflow/approval and basic doc control/templating processes to allow contributors to use tools they know? This would again offload work onto moderators and editors to transfer content to the final destination/engagement with 2 systems/workflows, but this may be offset by increased contributions.
Workflow that involves people doing work in some other tool, like Google Docs or Microsoft office, and then other people putting that into the docs tools, is cumbersome and (having experienced similar workflows in the past) terrible and
Unfun.
Honestly, I think the solution is what we already have plans to do:
Clarify the edit on GH process.
Fix the local dev process for Windows and make it more clear for everyone.
I'm currently working on the second point, after having spent a couple days with new contributors on windows.
I suspect that once those issues are cleaned up, we won't need to talk about changing the workflow and environment that much. The environment isn't that complicated, it just was never explained properly for windows.
I don't want to beat this topic to death, but I disagree that the environment isn't that complicated. It was complicated for me to start (on a mac) and it's likely complicated for new contributors who are not devs.
I agree that we can start by clarifying the GH edit process and fixing the local dev process on Windows, but we can and should continue to look for ways to have folks send in content without having to know how virtualenv or Docker.
I agree with @yanokwa that the process is very difficult for non programmers. Here is a quote from a direct message I recently received from a contributor:
Having gone through some of the contributory directions together at https://docs.opendatakit.org/odk2/contributing/ the directions/software are beyond the technical skill of anyone in the team to do correctly directly (economists who do survey research, not programmers, alas).
I felt similarly to @yanokwa as I was not able to find a solution for this person to contribute directly. This person has been using our docs for months and has valuable insights and essential improvements that they want to contribute, but they don't have the technical knowledge to build the docs, nor the time/resources to ramp up. We ended up deciding they would submit a formatted version of their changes and we would find other contributors (including myself) who would transcribe them, test them, and create pull requests.
I will echo the sentiment that improving the GH process is a good step, but we should also be considering how we can provide an avenue for non-technical contributors to submit changes.
I followed up with @elmps2018, asking if she had any suggestions, and got this reply:
In terms of a good model for contributing, that is a tricky one, as others in the thread have noted. It seems like you would want someone to review any edits, which makes for a better but more complex process. The formatting of the docs is much nicer than google docs, but I do wonder about that as a way for folks to comment/edit very easily and publicly, so that others could go through and "resolve" comments every so often and incorporate them in the more technical format. For projects with colleagues who use LaTEX (I do not), what they have done is given me a text file that still has all the formatting markup, but I can edit the "words." Not sure if something like that is possible in this case--formatting would still have to be addressed for things like adding sections. Will keep cogitating and let you know if I have any further ideas.
The standard and ease of use of the ODK documentation has changed beyond recognition in recent times; it is a joy to use now, we shouldn't loose sight of the great work that has been done. From a curator and editors point of view I really understand the want and need to retain the quality and consistency that has been achieved.
I still feel a focus on roles and the process (not technical) of contributing may be worth while. Often people with ideas aren't particularly structured within themselves, however their (documentation) ideas can be valuable and worth capturing.
Having previously worked for publishers, I have seen the relaxing of absolute requirement for submissions only accepted within a house style lead to a vast increase in quality submissions (and more work for editors where the process was complex to standardise).
The Style Guide for ODK has really good content, as does the Tips for Making Good Contributions. There is encouragement embedded deep in the content (I am not an impostor) ... however when I read "Contributing to ODK Docs" section and the first bullet is "Docs Technical Guide ... Docs as Code" I still sort of feel I might be one ...
The Tips for Making Good Contributions section has great content, but is structured in a way that could be off putting for a non-technical reader - An example in the first sentence "A PR should normally" ... What's a PR?! (I know what a PR is, but you get the point?)
Perhaps if the Contributing to ODK Docs section could start with Tips; split out the technical elements from this section and have Tips start with how one might engage (Where can I see documentation items that are needed/I could work on? How do I suggest an idea for some documentation to get an idea if it is worth writing it? If I have spotted errors, how best to suggest alternatives? Etc). The next section could be the Style guide (still mostly non technical, still in the comfort zone). This would perhaps help the non techie to emotionally engage and be a little more prepared for the learning curve ahead?
Currently I do agree that the learning curve is just too steep to engage directly for the non technical, but there isn't an obvious easy solution. If a solution or compromise can be achieved there are probably quite a few extra contributors ready to engage.
The work to clean up and simplify the Docs Contributor guide is IN PROGRESS and I have just submitted a very large Pull Request aimed at making the local editing and contributing process more clear.
(Note — this doesn't yet attempt to change the process itself. Only make the instructions correct and easy to follow.)
The Pull Request is a WORK IN PROGRESS and still has a lot of problems and broken things.
But, if any of you have the time and wherewithal to review it in its current state, that would be helpful.
(If you do review it, please read the full PR Message explaining the goals and current problems before diving in.)
) to contribute to docs. I'm thinking something like this would probably have resulted in a better experience...