Documentation Guidelines

This short article will help you better understand our documentation process and the proper guidelines and format for submitting your documentation.

Types of documentation

There are generally three main types of documentation that you can submit:

• Developer/tester/user documentation
  • How to setup a build environment
  • How to setup a QEMU testing environment
  • How to setup a VMware testing environment
• API Documentation
• Architectural and Utility Documentation
  • Kernel Architecture of NT/ReactOS
  • Security, Subsystem, Win32 Architecture of NT/ReactOS
  • Help files for applications such as notepad, calc
  • Reference guides for applications such as cmd
  • Generic OS help files (for Help & Support)

Developer/tester/user documentation

For this kind of documentation, feel free to simply use the Wiki and add your own tips/scripts/help on the appropriate pages. Many of them are currently under construction, and WaxDragon would surely appreciate your help!

API Documentation

This means documentation for API functions, similar as to the one you would find on MSDN, OSR, etc. This should go directly in the source code, following the current doxygen-recognizable format that we use:

/*++
 * @name CsrApiRequestThread
 *
 * The CsrApiRequestThread routine handles incoming messages or connection
 * requests on the CSR API LPC Port.
 *
 * @param Parameter
 *        System-default user-defined parameter. Unused.  
 *
 * @return The thread exit code, if the thread is terminated.
 *
 * @remarks Before listening on the port, the routine will first attempt
 *          to connect to the user subsystem.
 *
 *--*/
NTSTATUS
NTAPI
CsrApiRequestThread(IN PVOID Parameter)
{
...
}

Note that there are many kinds of similar headers used throughout the source code. These are WRONG and simply reflect the lack of a standardized header. If you'd like a helpful janitorial task, creating proper headers for every public function in the module would be very helpful. Eventually, all public and private functions in ReactOS modules should have a header like that. From there, Doxygen can create the documentation, so you don't have to worry about any additional formatting.

Architectural and Utility Documentation

So, you know the internals of DPC Queuing? You've got the LSA algorithms written in the palm of your hand? You know all the commands that the NT cmd.exe supports? This is the documentation job for you. By far the lengthiest and most arduous type, it's also possibly the most useful. Although architectural documentation exists in books such as Inside Windows 2000, Windows NT Internals, Win32 Programmer's Cookbook, etc. (and some doesn't exist at all), none of it is freely available under a Free documentation license such as the GNU FDL or Creative Commons. Applications such as calc, notepad, and others, also need relevant information in a .hlp or .chm help file, so that users can read about them (we can't just copy/paste the proprietary .hlp/.chm files)

The submission types are as follows:

• For architectural documents: a high-quality proof-read technical document clearly explaining the technical topic that you are discussing. Preferably in .pdf format or OpenDocument, or .doc as long as it doesn't contain any features which would make it unreadable by OpenOffice.org or Abiword. You should post this to the ros-dev mailing list for review.
• For application documentation, including command-line reference guides and OS Help & Support: a compiled .hlp and .chm file designed and structured in a similar way to the official documentation (so that users will be familiar with it). You must NOT simply copy/paste the official documentation and call it your own. For both .hlp and .chm, make sure that you still have the original source files (e.g. HTML) as well. Please post those to the ros-dev mailing list for review. If you do not have a .hlp/.chm compiler, we can do it for you, but we would appreciate it if you made sure that they will show up fine in the help viewer. (There are several guides online on how to create good help files, and use the Windows ones for guidance).