search

cproctor / qualitative-coding

Qualitative coding for computer scientists
Other
9 stars 3 forks source link

Documentation clarification: Line numbers, coding file? #56

Closed cmaimone closed 1 week ago

cmaimone commented 3 weeks ago

Just as a note, as you indicate for Sublime Text, when VS Code opens for me, I have two tabs -- the files don't open side by side (I'm using a mac if it matters). So it's not as intuitive that the values in the codes.txt file should go in the same line number as the lines in admin.txt. The screenshot (Figure 1) helps, as the text itself wasn't completely clear that the line numbers need to match.

Even when the documents are side by side, they don't necessarily scroll together, so being very clear that the line numbers need to match is key. Keeping the two files lined up is actually a bit challenging.

I was also confused by "an empty document for codes" - is this an entirely new document without any filename, or is it codes.txt? I assumed codes.txt, but since there's only one such file in qc_demo, that doesn't seem right. And when I looked at the code stats after, they didn't seem to reflect the codes, so I'm thinking maybe that's not the right file?

re: https://github.com/openjournals/joss-reviews/issues/7031

cmaimone commented 3 weeks ago

For context, I ran opened a coding session in the qc_demo project to code the admin.txt file

cproctor commented 3 weeks ago

This is the intended behavior. The desired coding experience is to have the corpus file and the temporary coding file (codes.txt) side-by-side, scrolling together. Unfortunately, there isn't a way to invoke VS Code from the command to achieve this, so you need to manually drag them side-by-side. If you have the VS Code Sync Scroll Extension installed, the two side-by-side panes will scroll together.

The installation instructions are updated to include the Scroll Sync Extension, but I just realized that the vignette contained its own "Installation" section, which I had not updated. I removed the redundant installation instructions and linked to the correct instructions.

(The most graceful usage of qc is with vim, where you can get the desired coding behavior through a command-line invocation. I chose to introduce qc with VS Code in the vignette because many potential users will not know vim.)

I believe this issue can be closed, but please let me know if you think I should make any changes to make this clearer. Thanks!

cmaimone commented 3 weeks ago

It's more that I'm confused about how codes.txt is supposed to work. The vignette at least I don't think specifically named the file (that it is called codes.txt), so that was some of the confusion. But I'm also confused about how it works with there just being a single file. What prompts an update to the database of codes after you edit that file? The process stays open in the console once the files are opened in an editor, I'm not clear on the expected steps to close that out (other than killing the process).

cproctor commented 3 weeks ago

I just added an explanation of how codes.txt is used in Create a new project:

After each coding session, qc reads codes.txt, updates the database with changes in coded lines, and then deletes codes.txt. This file therefore serves as an interface between qc and your editor.

The second note in this section also hopefully adds clarity with an example of how you could write a custom "editor" to do automated coding.

You could automatically apply codes to a document by writing a script and defining it as an editor (see editors); the script would receive the path to a corpus file and the codes file, and would write codes into the codes file. This opens the possibility of methodological innovation. For example, when we were analyzing student-written computer programs, we combined manual qualitative coding with automated static analysis of the programs, which added codes marking syntactic structures and manipulation of variables. This allowed us to integrate what students were doing (via our qualitative coding) with how they were doing it (via static analysis).

Specifically answering your question, the hanging process in Terminal waits for a signal from the editor that editing is complete (because you saved and closed the files). The process of invoking the editor was launched by qc, so once the process completes, qc can continue with reading codes.txt and updating the database accordingly. Then the qc code process ends.