Encountering coding problems and solving them - grambank/grambank GitHub Wiki

This text outlines the workflow what to do when coders encountering coding problems.

As you are coding, you will undoubtedly encounter an issue that is difficult to resolve. The articles of this wiki were created to resolve most of the issues encountered by coders. If you struggle with a particular feature, consult the wiki page for that feature. If the wiki page does not resolve your issue, please contact your node leader or the patron of the feature. The patron of the feature is mentioned at the bottom of each feature article. You can contact the patrons by posting an issue on the issues page of the GitHub repository. Node leaders are happy to take any kind of question and can help direct you to the right person if they do not know an immediate answer to your question.

Decisions at meetings are recorded in our meeting notes. You can find and search the meeting notes of previous and current meetings in our shared Google drive folder. Coding discussions also happen in our GitHub issues, which are also searchable.

A quick guide what to do when encountering coding problem

If you cannot decide how to code a data-point after 20 minutes of solitary thinking, follow these steps. Proceed to each next step if the previous step does not solve the issue.

  1. Read the feature description thoroughly.
  2. Look through old meeting notes (see shared Google Drive folder) and GitHub-issue threads.
  3. If possible, do a quick search on the internet and of your university library for existing literature on the subject.
  4. Talk to your node leader and fellow coders at the scheduled node meetings. Submit a description of your problem in advance in the meeting agenda.
  5. Bring up the issue as a GitHub-issue, tagging the relevant patron and clearly stating which feature(s) you have trouble with. Give some context, mentioning the language, the source you are using and quotes or examples from the source. Use the tag 'coding problem'. Please limit each thread to one problem at a time. Do not mix different separate topics in one thread.
  6. The patron will respond and discuss the issue with you. Other coders and associated people are also welcome to partake in the discussion, but are not required to follow all twists and turns. The patron is responsible for leading the discussion, keeping it from derailing and for closing the issue and making a clear statement about what has been decided.
  7. If the patron does not respond in reasonable time, give them a poke or send an e-mail to [email protected].
  8. The final conclusion is stated by the patron in the GitHub-issue thread. The patron is responsible for updating the wiki article if necessary.
  9. If needed, go through your previous coding and update so that it is in line with the new information the discussion has revealed.

GitHub issues

GitHub allows users to discuss issues and to can keep track of ongoing discussions. You can also assign people to issues, give them labels, etc. The issue section is where detailed discussions of coding issues take place which are not resolved at the regular meetings. Coders start issues, patrons answer, follow up and close them. After an issue is closed, the patron is tasked with writing up conclusions.

There are a couple of things to keep in mind when posting issues and asking questions:

  1. There are no stupid questions.

There are many coders and many are new. Grambank coding is not easy. It is normal that you do not understand everything. Remember that you are not alone! Your question will most likely help other coders as well. That said, we encourage reading the feature documentation and talking to others in your local group so that conversations on GitHub can be as efficient and informative as possible.

  1. Provide context to your issue.

When posting an issue to the group, make sure to state enough context so that others can help out efficiently. Type out the feature number and question in full and describe the language-specific situation with examples, if possible.

If your issue is a question for clarification of a feature, tell us if there are any particular terms you do not understand. Ask for general clarification or for examples.

  1. Post one issue thread per issue.

Issue threads discussing several different issues at once easily become confusing. You can address more than one Grambank feature or languages in one issue, as long as they are related to the same challenge.

  1. Consistency

It is important that we are consistent, and this is a very hard task. Therefore, please keep in mind that our comparative concepts need to be pragmatically executable, compatible with previous coding and interesting rather than theoretically perfect.

  1. If not solved

If the issue is not solved in an issue, it may be discussed at the next meeting. The final coding could still be a ?, for example if it is not clear what the best interpretation of a language specific situation is for Grambank.