Difference between revisions of "Documentation Guidelines"

From ReactOS Wiki
Jump to: navigation, search
(Developer/tester/user documentation)
(revert back to English)
Line 1: Line 1:
==介绍==
+
==Introduction==
  
你想提交ReactOS文档吗? 非常棒! 这份简单文档将帮助你很好的理解我们的文档进程并且说明提交文档和一些格式指导。
+
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
** 怎样安装QEMU测试环境
+
** How to setup a QEMU testing envionment
** 怎样安装虚拟软件测试环境
+
** How to setup a VMWare testing environment
** 等等...
+
** etc...
* API文档
+
* API Documentation
* 体系结构上的和工具上的文档
+
* Architectural and Utility Documentation
** NT/ReactOS的内核体系
+
** Kernel Architecture of NT/ReactOS
** NT/ReactOS的安全, 子系统, Win32体系结构
+
** Security, Subsystem, Win32 Architecture of NT/ReactOS
** 应用程序的帮助文件如记事本,计算器
+
** Help files for applications such as notepad, calc
** 应用程序参考指南,如CMD
+
** Reference guides for applications such as cmd
** 一般的OS帮助文档 (帮助和支持)
+
** Generic OS help files (for Help & Support)
  
==开发者/测试人员/用户文档==
+
==Developer/tester/user documentation==
  
对于这些各种类型的文档, 自由的简单地使用Wiki同时加入你所拥有的技巧/脚本/帮助在适当的页面. 许多人正处于建设中, 并且[[Waxdragon]] 会十分的感激你的帮助!
+
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==
 
==API Documentation==

Revision as of 06:06, 4 July 2006

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...
  • 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 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

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).