Documentation Guidelines

From ReactOS Wiki
Revision as of 02:33, 13 October 2005 by Alex_Ionescu (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Introduction

So, you want to submit documentation to ReactOS? That's great! 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 envionment
    • How to setup a VMWare testing environment
    • etc...

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 whould 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 standarized 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
    • 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)

So, you know the internals of DPC Queueing? 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 lenghtiest and most ardous 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, etc, 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 properietary .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 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 (.html, etc) files 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).