Documentation

[piranha]

I am going to start writing documentaion for my OS and I want to know your methods. I am writing it as I go along.

[Alboin]

I think documentation should be written at the end of the first stable release of your operating system, and updated from there.

Writing documentation while your OS is dramatically changing doesn't make much sense to me.

[frank]

I have two different viewpoints on this. One is for end user documentation and the other is developer documentation(function documentation and stuff like that.)

I believe that end user documentation ie stuff that tells the user how to use your os should only be written on a completed operating system prior to release. You can of course write it in pieces if you know that certain parts are not likely to change in the future.

The other side or the issue is developer documentation. What I mean by that is documentation for system calls and functions inside of the kernel that only you and other developers for your operating system should be able to see. I think that this should be written as you go along, so that you can look back at a function several weeks from now and know what it does and so that other people will know what it does.

[AndrewAPrice]

I write documentation (like my user libraries) when I just finished a checkpoint and I marvel at it and I'm still in the marveling stage before I plan what to do yet.

[Brendan]

Hi,

For me there's several types of documentation.

First there's design notes. These aren't really "documentation" - before I do something new I write out how it's meant to work and then try to find problems and ways to improve it. Eventually I'll decide it's a silly idea or implement it, and forget about the orginal notes.

Then there's documenting code. For this I've got a utility that allows me to put titles, headings, explanations, HTML links, etc into the ASCII source code. I document the code while I write it (most of the time). Because my OS is made up of many modules, I've also got HTML pages that describe each module and show the relationships between modules. These I normally do before starting a new module (and then correct them if/when necessary).

There's also misc. specifications and references. These describe things like the state the computer should be in when the OS goes from one stage to another (e.g. during boot or during shutdown), details of the kernel's API/s, messaging protocols for some things (VFS, GUI, etc) and other things. I start writing these before writing the code, and then update them or correct them if/when necessary. For example, if I decide to create a new kernel API function I'll update the documentation, then write the code for the function.

Then there's a system programmer's guide and an application programmer's guide. These provide an overview of how things are done, give advice and contain other information needed to write software for the OS. These documents also use the specifications and references (e.g. some example code showing how something is meant to be used might have HTML links to the kernel API reference for each function in the example). I tend to leave this documentation until later.

There's also a user's guide. This contains information on how to install, configure and maintain the system. I tend to leave this documentation until later too, although I do keep some parts of it up to date (a list of accepted boot script variables and what they do, and a description of each CPU flaw that may be detected). It's just easier to write these things down than to remember them (or search through the code to find out the information).


Cheers,

Brendan

[pcmattman]

When it's done, it's done. Then you can concentrate on writing the documentation.

At the same time I often document code as I go (and type out quite a bit when I'm confused - see the top of fs.cc in my CVS repository to see what I mean) and spend hours designing the next thing for my OS - just nothing ever gets done on paper. Has something to do with the lack of paper and pens thanks to school requiring them all.

My 2 cents.

[Dex]

Documentation whats that ? . This is something i find very hard to do, i would much rather spend that time coding. Lucky we have other members of our team who are not dyslexic like me.
But good documentation is a must. But as most OS evolve, so are constantly changing, if you write then too soon, you will probably need to keep changing them .

[inflater]

For PortixOS, there will be only one documentation, and that's the tech reference, what type of the OS is (monolithic single-tasking, don't you Dex [and inflater]? ), hooked interrupts, program specification, etc.

Users Guide? I do not need this stuff... Everybody knows what ERASE, CD, USE {FD0, HD0, ...}, HALT {SUSPEND, STANDBY}, EXIT, FASM, UNINSTAL, KEYB {US, UK, SK}, RESET, SETUP, HELP, ABOUT, LIST {directories}, TYPE {display a file} ... etc. would do

That gives me a idea: What commands has your operating system? Mine has like mentioned above (cmon this is general ramblings, off-topics permitted )

inflater

[frank]

Right now the shell in my OS is still integrated into the kernel so that I can easily test kernel functions. As of right now I have the following commands:

pci - lists pci devices
help
echo
time
date
log - prints the logfile
run - will eventually run a new process
about
info - prints kernel specific info like number of irqs fired and stuff like that
cls - clear screen
foreground
background
flush
size - prints filesize
exists - tests for the presence of a file
ls, dir
read - prints the contents of a file
more - same as read with screen pauses
cd - doesn't work
del
restart, shutdown

and then a hand full of other debug functions to test certain concepts I am working on. Of course none of these functions are useful to an end user.