Do you use a design document?

[Lionel]

Hello OS Developers,
I am currently writing a design document for my kernel and OS, and I was wondering, is the community doing the same, or is it a waste of time. So I was wondering...

• 1. Do you use a design document for your OS?
  2. Why do you, or why do you not?
  3. Have you lost sight of your goals with/without a design document?
  4. Is it worth it?

If you want, I can share the link to the current version of the design document.

Thank you,
Lionel
PS. Writing this from Chrome OS!

[bluemoon]

Yes. OS development goes for years, especially for hobby you might pause a few months; without document you will get lost.
The document also serve the purpose of connecting the dot, to prove your concept, as it's a standard procedure of software development.

[Lionel]

Thanks for the quick reply bluemoon,
So a design document is essential to writing software, and it helps you from loosing sight of the projects goals, without straying to far ( as long as you stick to it).
Now I want to know if you made a design document (assuming yes based on your response), and how long it took, how much it helped you.
Thanks,
Lionel

[bluemoon]

My document is constantly revised (adding stuff with was place-holder)so it's hard to count; but I usually spent enough time until I got the whole idea, do experiment and proof of concept, before writing any real code, not only for OS development but also my real life work.

[NickJohnson]

I do sometimes write out some sort of design document before writing code, but it tends to be more of a way to get my thoughts out abstractly than a form of documentation. I also usually do it on paper, so I can draw diagrams more easily. Then I move on to writing header files as a sort of design contract, then to actual coding. This sort of cycle takes between a day and a week, typically, but it depends on the complexity of the component.

Usually the final design differs from the original idea somewhat, but I don't go back and change the design documents; I just keep them in a notebook as a log of things I've thought of. Final documentation is a separate effort, and I only really do that once a system has been stable for a while and I know I'm not going to redesign it.

[GAT]

I keep some paper handy near me so I can sketch out ideas and make sure they are feasible before I dive in and code them, that's the closest to documentation I come.
IMHO working on documentation just distracts you from the actual work at hand.

[VolTeK]

I use Microsoft office to write full documents over the How-It-Works of a sub system in my kernel. For each subject, Disk or Memory manager, or the process manager i have a document in each folder explaining how each work. For future terms when i want a team, they just have to read the document and already know what to expect in the source. (Unless they do not understand assembler)

[neon]

Interestingly not as much documentation as I probably should. My reasoning stems from the fact that the software is ever changing and growing; maintaining full documentation with the software suite is an awful lot of work. More complex systems are documented in-code or separate files (sort of like an "idea notebook") to explain its design; the code itself supports Doxygen for auto-documenting system APIs. Actual documentation is written for each system once the particular software component is finalized.

[gravaera]

Yo:

I have about two or three notebooks full of design notes, iterations and diagrams, monologues, research notes and other related goodies. I've never seen a formal design specification, but that's about as close as I get to a design document.

--Peace out
gravaera

[bewing]

I just code it all by the seat of my pants. I let the machine tell me how it wants the system to work -- if it codes easily then that's the right way to do it. Once it's working and beautiful, then I write a document. If you document it beforehand you may not get lost, but you will force yourself to do things the machine does not want to do.

[Jezze]

What bewing said.

[Lionel]

brewing:
Why don't you before hand just write out a general document? Not going into "x should be incremented by y divided by z squared" mode, but simply, "This class manages the systems memory, and calls subsystems to actually allocate and unallocate memory". I usually do something like this, so I'm sure of the function of the class, but not sure how to do it. This allows you to maintain the same function, while allowing you to make it work easily.

gravaera:
Wow, that is a lot of notes. Do you find that you use it frequently?

neon:
I meant not of the actual code being documented, merely the main concept. Do you have any "Overview" documentation, that gives you a general overview of what your OS does?

VolTeK:
That is a very good idea. I think I'll use that in addition to a full overview design document.

GAT:
I sort-of do that in my mind, instead of on paper. And I'm going to have to disagree with you. IMHO documentation is important for staying true to your goals.

NickJohnson:
Header files as a contract? That actually seems like a good idea.

bluemoon:
I see, do experiments on the idea to make sure it is worthwhile before writing any code, and make sure you develop the idea in the design document.

EDIT:
Do you think my design document is good so far (it's incomplete):
Design document (In Google Docs)

[bewing]

Why don't you before hand just write out a general document? Not going into "x should be incremented by y divided by z squared" mode, but simply, "This class manages the systems memory, and calls subsystems to actually allocate and unallocate memory".

1) Because I have a mental vision of 90% of how I want it to work, and if I'm wrong then that is the part that wouldn't help to write down anyway because I'd have to change it.

2) Because my OS is mostly in ASM, so I have no classes, just arrays and structs. I hate OOP.

[NickJohnson]

Because my OS is mostly in ASM, so I have no classes, just arrays and structs. I hate OOP.

But you still have object (i.e. structure and array) relations. Those are much easier to draw than they are to write out. That's not even mentioning state transition diagrams.

[turdus]

@OP: Trust me, beside the main concept, document all interfaces without stint too. You'll hate it, but later you'll be very thankful. Finish this specification as if the programmer after you would be a psycho who knows where you live. Give it a time, work out every details. Don't stop until you're absolutely sure the thing stands as a whole, and every piece is in place (in theory at least). Then, and only then, as a first guinea pig of your own specification, implement it on both kernel and userspace side. Go step by step, follow your documentation as if it were written by someone else. Quick'n'dirty coding acceptable for the first time (can speed up things, just don't forget to replace later with proper code). Sometimes, in rare cases, there'll be a need to modify the spec as you go on with coding (for example performance reasons or spotted bad design decision), but the basic structure should not change. If it changes that means you have no clue what's necessary behind the scene to make an OS up and running, so go back and learn more before trying it again. When (and if) you've finished the implementation, as a bonus, you'll have a 100% accurate API documentation that can be passed over to third parties to write their own userspace apps or kernel modules for your OS.

@bewing: what's wrong with OOASM? It's perfectly doable, see http://en.wikipedia.org/wiki/High_Level_Assembly.