Commenting on docs at my workplace has taken the norm of putting general doc comments on the title or introductory sentence, and general comments about a section on the header, and comments about missing topics on the TOC. And, of course, comments about specific items in the text on that item.
It does put a lot of comments too early, but it also doesn’t bury them after all the nitpicks. The technique to resolve that problem is to read (or at least skim) the entire doc before looking at any comments.
Yeah, that’s definitely a better norm than the status quo. The issue I still have with it is that the inline comment box is really tiny (read: thin) and has a max character count below what I want to write more than 50% of the time, which sends signals like “You’re not supposed to write that much” and just generally makes it inconvenient. I want (for myself) an unrestricted space to find out what I think and how much I have to say (by babbling a bunch).
There are times (not always, and I don’t recommend it generally) that instead of inline comments, I create my own comment doc, and my comments on the doc in question include links to anchors in that doc. This is especially valuable for early technical documents where there’s going to be a lot of iteration, and it’s OK for discussion to be spread out a bit, expected to consolidate on the next major revision (which will be a new doc, and the old doc and comments kept for historical purposes only.
Commenting on docs at my workplace has taken the norm of putting general doc comments on the title or introductory sentence, and general comments about a section on the header, and comments about missing topics on the TOC. And, of course, comments about specific items in the text on that item.
It does put a lot of comments too early, but it also doesn’t bury them after all the nitpicks. The technique to resolve that problem is to read (or at least skim) the entire doc before looking at any comments.
Yeah, that’s definitely a better norm than the status quo. The issue I still have with it is that the inline comment box is really tiny (read: thin) and has a max character count below what I want to write more than 50% of the time, which sends signals like “You’re not supposed to write that much” and just generally makes it inconvenient. I want (for myself) an unrestricted space to find out what I think and how much I have to say (by babbling a bunch).
There are times (not always, and I don’t recommend it generally) that instead of inline comments, I create my own comment doc, and my comments on the doc in question include links to anchors in that doc. This is especially valuable for early technical documents where there’s going to be a lot of iteration, and it’s OK for discussion to be spread out a bit, expected to consolidate on the next major revision (which will be a new doc, and the old doc and comments kept for historical purposes only.