News for hackers. Stuff that matters.
Re:Redox: A Rust Operating System by talles on Tuesday September 29, 2015 @01:09PM (#10297721)
> Redox is a Rust based operating system, designed to be modular and well documented.

How does one design something to be well documented?

Re:Redox: A Rust Operating System by elihu on Tuesday September 29, 2015 @02:33PM (#10298473)
The 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.
Re:Redox: A Rust Operating System by steveklabnik on Tuesday September 29, 2015 @01:40PM (#10297975)
Well, 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.
Re:Redox: A Rust Operating System by talles on Tuesday September 29, 2015 @02:17PM (#10298342)
(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.

Re:Redox: A Rust Operating System by vezzy-fnord on Tuesday September 29, 2015 @01:51PM (#10298095)
Literate programming.

Though obviously in this case it was ambiguous punctuation.

Re:Redox: A Rust Operating System by jackpot51 on Tuesday September 29, 2015 @07:18PM (#10300549)
I 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.

Re:Redox: A Rust Operating System by conceit on Tuesday September 29, 2015 @01:47PM (#10298059)
the sentence is missing the oxford comma before "and"
Re:Redox: A Rust Operating System by retbull on Tuesday September 29, 2015 @01:11PM (#10297734)
Like all designs. You write it down and immediately throw it away and do w/e you want.