I am Itoh from ATL. Mr. Yoshimura have worked together to write a book entitledA Guide to Document Creation System Configuration. Our target readership consists of engineers rather than people who write books for a living. The book introduces means for engineers themselves to efficiently create documents (specifications, manuals, etc.) that support their works. It also includes content useful for the creation and management of company internal documents that require proofreading. We definitely recommend it to individuals who are concerned with quality management of in-company documents. This book is scheduled to be published on March 25.

Content and Overview

This book deals with a number of topics useful for document creation. Each topic is introduced below.

• Version management systems
  Software engineers use version management systems when developing software. It can be used to identify problems or reproduce problems when version management systems are deployed. This book provides concrete examples to explain the flow of document writing using Git, a version management system, and its hosting service GitHub.

• Markup languages and document creation tools
  Through the present a number of markup languages such as HTML and TeX have been proposed. This book introduces two simple markup languages, Markdown and AsciiDoc. Even though the use of AsciiDoc has been the major trend abroad, it has not been prepared for Japanese language documents. In addition to explaining how to write using AsiiDoc, this book also provides a detailed explanation of how to specify how documents will appear when converted to an output format (PDF or HTML).

• Document inspection tool
  When the document is written by multiple individuals, the problem of inconsistencies in the terminology and punctuation used arises. This book introduces methods for automatically detecting problems in documents by using RedPen, the document inspection tool. RedPen supports markup languages (AsciiDoc, Markdown, etc.) and can be used to automatically inspect more specialized documents, such as product manuals and in-company documents.

• Continuous integration
  The customary continuous inspection for problems in final products (continuous integration) has spread throughout software development. This book introduces methods for incorporating the continuous integration support service Travis into document creation.

Refer to the support page for sample used to explain each topic.

Final Impression

Below, we expound upon our impressions upon completion of this book.

• Acknowledgments
  The topics dealt with in this book have nothing to do with algorithms for making appearances or with trendy technologies. Nevertheless, would like to express our appreciation to Gijutsu-Hyohron Co., Ltd., who greenlighted the publication of this book.

• In-company documents
  After we finished writing it, we found a Qiita article that referenced this book. The article stated that it would be best to dispense with the use of spreadsheet software in the creation of process documents. Though we were not aware of it at the time he wrote this book, I agree that our handling of in-company documents with spreadsheet software was inefficient. In the near future, I would like for there to be a transition of technical documents including process documents from spreadsheet software to light markup languages and version management systems, and I would be pleased if this book contributed to that.

• Natural language
  Software engineers learn 10 or more programming languages at which they are both adept and maladroit. Nevertheless, the programming languages and idioms used change with the times. Natural language is one language that is indispensable to software engineers. Also, natural language is necessary in order for their own works to be taken over by others. I feel that it might be better if a little more attention was paid to know-how pertaining to writing in natural language. There is also still substantial room for improvement in the topics raised in this book. As readers, we look forward to the release of books in the future intended to improve writing environments.

This Book’s Manuscript

The GitHub repository was used in the writing of this book. Throughout the writing of this book, we received a great deal of advice from Mr. Takaya of Gijutsu-Hyohron Co., Ltd., pertaining to GitHub issues. Some of this advice was used in the automatic inspection of this book with RedPen.

For example, Mr. Takaya commented that strings of Chinese characters were difficult to read. The following shows the creation of the function (long_kanji_chain.js) after receiving this comment.

Some of the source files for this book, including the functions treated, will be publicly released. Please have a look at them. Also, v1.6, the next version of RedPen to be released, is planned to support the functions used when writing this book.