Doc commenting in HTML output?


#1

Hi all,

Is anyone aware of tooling that will let reviewers comment on HTML output for docs?

We’re looking to manage content in asciidoc/markdown (you can guess my strong recommendation, but front-end tooling is dominating the discussion at the moment). But it’s the strong sense of the team that reviewers will need to review in the output format, not in source.

Any suggestions/remarks/feedback/ideas much welcome!

thanks,

Jennifer


Early Drafts for git/markdown writers
#2

I guess Code Collaborator is not the type of thing you are looking for? We use that for source code, and put a link to the output so people can see that and comment on the source.

Oxygen might have some tools that help, but I never used it for this particular purpose.
http://www.oxygenxml.com/xml_editor/change_tracking_and_review.html


#3

Yes Lois, the kind of workflow you describe with CC is what I’ve done at other companies, but in this case our team is unsure of just who our reviewers will be, and there’s some desire to provide a GUI-based experience for some.

That said, we’re also looking at source markup review in github (not code review strictly speaking, but review of source asciidoc or markdown), with pull requests or issues. Or possibly a HipChat room for comments on the output separate from said output.

Just exploring. Some of our issues with designing a system come, I think, from the fact that PM, doc, and API design overall are completely separate from engineering. Also new to me …


#4

That’s an interesting organizational setup. It sounds like it might center Product Management, which could be good in some ways.

I don’t know these, but I wonder if any of them might have some applicability for you?


#5

I’ve tried various methods for content review. Most of them suck. After someone gave me a 40 page Word doc with various columns listing doc URLs, headings, and comments about what to change, I decided to do something different – I implemented the Github pull request workflow for doc reviews.

I put my content in a private Github repo and created a branch called “review.” Then I added a button on each page of my docs that pointed to the corresponding source page for that topic. Clicking the button takes the person directly to the Github source page in the review branch.

I also added my reviewers as collaborators to the project so they could edit directly on the branch (instead of forking the entire project, as you would need to do if you’re not a project collaborator).

I told the reviewer to just add comments in brackets with her initial at the beginning.

So far it’s working pretty well. I periodically check out the review branch and make all the changes from the reviewer. When finished, I create a pull request to merge the review branch into the master.

In general, during the review period I work in the review branch as well. I don’t want to enter merge conflict hell by making lots of updates to the master branch while reviewers are adding a ton of contents in the review branch.

Right now I just have one thorough reviewer for the project. For others who just give me 2 line comments in emails, this method is overkill so I just continue with email threads for those types of reviewers.

The Github branching approach is more common in software development projects. I think it will work well enough for content review. The main benefit is tying the comment to the page the user is viewing. With the previous Word doc review method, the comments were mapped to the source like spaghetti spilled on the floor.

I’m curious to know if others have used this method for doc reviews. I’m also deliberating with using Bitbucket instead of Github. Our devs us hg instead of git, so it might be a better fit for version control consistency.


#6

This link has a number of outdated tools, many of which aren’t operational at all. Try some of these instead, maybe one of them will suit you - https://blog.zipboard.co/website-annotation-and-design-collaboration-tools-411b817d0c99