Here at Facebook, the Memcache team is taking the bold step of designing a system before building them. We believe this will lead to fewer bugs over the long-term, while serving to document our code beforehand instead of afterwards (Ha!)
We have looked at a few possible tools to write and review these design documents:
- Microsoft Word
- Zoho Docs
- Word has great review tools for text-heavy (non-code) documents. It works great except that it doesn't solve the versioning issue at all -- we have to manually version the documents.
- Zoho docs solves the versioning issue (kinda) and I hear it has decent review tools, but it saves the document after every key press, so you end up with thousands of 'revisions' when really we only want revisions when we state it explicitly.
- Differential is great for versioning, but poor for reviewing non-code documents. We tried this with the Scaling Memcache at Facebook paper and it wasn't a great use of differential.
What we would really like is something with versioning like differential, rich text editing like many of the tools in phabricator, and review tools optimized for non-code prose. This last point is especially important: we need to be able to:
- call out specific words (not just lines)
- call out sentences that may be partially on several lines
- suggest edits (perhaps inline, as in Word?)
- see diffs of the text that are more intelligent than line-based diffs (eg, if a sentence re-flows due to line-wrap, we can't have that be highlighted as changed text. We need a word-based differ).
Does this seem like a reasonable thing to support for the Phabricator suite? Is there already a tool that does a great job at this that I'm missing?