5 ms·
> Redox is a Rust based operating system, designed to be modular and well documented. How does one design something to be well documented?
by talles 11y ago
> Redox is a Rust based operating system, designed to be modular and well documented.
How does one design something to be well documented?
- retbull 11y agoLike all designs. You write it down and immediately throw it away and do w/e you want.
- steveklabnik 11y agoWell, depending on your definition of "Design", you do things like 1. Ensure you have the tooling to produce nice docs. 2. Build time to write docs into your planning. 3. Actively try to find people who will write good docs. 4. Focus on making your code understandable, so that the eventual docs will make sense. Spaghetti code is hard to document.
- talles 11y ago(IMO) that is taking documentation in consideration while designing, and not designing to (it's not the actual purpose of the design). Pedantism aside, I guess it was a phrasing issue.
- conceit 11y agothe sentence is missing the oxford comma before "and"
- vezzy-fnord 11y agoLiterate programming. Though obviously in this case it was ambiguous punctuation.
- elihu 11y agoThe other comment about the Oxford comma is probably correct, but I'll answer the question anyways: I have found that I design things differently if I'm doing the documentation up front. I have known myself to re-write functions because it seemed like too much work to describe what the function is supposed to do in plain English. If I had put off documentation for later, I would have built a different system.
- jackpot51 11y agoI am the author of Redox. I didn't choose that line well, so I simply removed that text. I meant that I would like it to be well documented, not that it would be designed around documentation.