manual/src/docs/tutorials/howto-writing-docs.txt

///////////////////////////////////////////////////////////////
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *   http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing,
 * software distributed under the License is distributed on an
 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 * KIND, either express or implied.  See the License for the
 * specific language governing permissions and limitations
 * under the License.
///////////////////////////////////////////////////////////////

[[community-docs,Writing Documentation]]
= Writing Zest™ Documentation =

The documents use the asciidoc format, see:

* http://www.methods.co.nz/asciidoc/[Aciidoc Reference]
* http://powerman.name/doc/asciidoc[AsciiDoc cheatsheet]

The cheatsheet is really useful!

You need to install `asciidoc` and `docbook-xsl`.


[[community-docs-overall-flow,Documentation Flow]]
== Overall Flow ==

TIP: To generate the website locally use `./gradlew -p manual website`. Output is in `~/manual/build/docs/website`.

Each (sub)project has its own documentation, in 'src/docs/' and all the Asciidoc documents have the +.txt+ file extension.

The documents can use code snippets which will extract code from the project. This is preferred way to include
source code in the documentation, since any refactoring will be reflected in the documentation.

The above files are all consumed by the build of the manual (by adding them as dependencies).
To get content included in the manual, it has to be explicitly included by a document in the manual as well.

The whole documentation set is generated from the _*manual*_ module in the SDK, and we are currently only creating the website.
The User Guide and Reference Manual are future projects.

== Headings and document structure ==

Each document starts over with headings from level zero (the document title).
Each document should have an id.
In some cases sections in the document need to have id's as well, this depends on where they fit in the overall structure.
To be able to link to content, it has to have an id.
Missing id's in mandatory places will produce warnings, or even fail (depending on severity), the build.

This is how a document should start:

[source]
----
[[unique-id-verbose-is-ok,Remember This Caption]]
= The Document Title =
----

To push the headings down to the right level in the output, the +leveloffset+
attribute is used when including the document inside of another document.

Subsequent headings in a document should use the following syntax:

[source]
----
== Subheading ==

... content here ...

=== Subsubheading ===

content here ...

----

Asciidoc comes with one more syntax for headings, but in this project it's not used.

== Writing ==

Try to put one sentence on each line.
Lines without empty lines between them still belongs to the same paragraph.
This makes it easy to move content around, and also easy to spot (too) long sentences.

== Gotchas ==

* A chapter can't be empty. (the build will fail on the docbook xml validity check)
* The document title should be "underlined" by the same
  number of +=+ as there are characters in the title.
* Always leave a blank line at the end of documents
  (or the title of the next document might end up in the last
  paragraph of the document)
* As +{}+ are used for Asciidoc attributes, everything inside will be treated as an attribute.
  What you have to do is to escape the opening brace: +\\{+.
  If you don't, the braces and the text inside them will be removed without any warning being issued!

== Links ==

To link to other parts of the manual the id of the target is used.
This is how such a reference looks:

[source]
----
<<community-docs-overall-flow>>
----

Which will render like: <<community-docs-overall-flow>>

[NOTE]
Just write "see \<<target-id>>" and similar, that's enough in most cases.

If you need to link to another document with your own link text, this is what to do:

[source]
----
<<target-id, link text that fits in the context>>
----

NOTE: Having lots of linked text may work well in a web context but is a pain in print, and we aim for both!

External links are added like this:

[source]
----
https://zest.apache.org/[Link text here]
----

Which renders like: https://zest.apache.org/[Link text here]

For short links it may be better not to add a link text, just do:

[source]
----
https://zest.apache.org/
----

Which renders like: https://zest.apache.org/

It's ok to have a dot right after the URL, it won't be part of the link.

[source]
----
https://zest.apache.org/.
----

Which renders like: https://zest.apache.org/.

== Text Formatting ==

* *Bold* - just don't do it, the editor in charge is likely to remove it anyhow!
* \_Italics_ is rendered as _Italics_
* \+methodName()+ is rendered as +methodName()+ and is used for literals as well
* \`command` is rendered as `command` (typically used for command-line)
* \'my/path/' is rendered as 'my/path/' (used for file names and paths)

== Admonitions ==

These are very useful and should be used where appropriate.
Choose from the following (write all caps and no, we can't easily add new ones):

NOTE: Note.

TIP: Tip.

IMPORTANT: Important

CAUTION: Caution

WARNING: Warning

Here's how it's done:

[source]
----
NOTE: Note.
----

A multiline variation:

[source]
----
[TIP]
Tiptext.
Line 2.
----

Which is rendered as:

[TIP]
Tiptext.
Line 2.

== Images ==

IMPORTANT: _All images in the entire manual share the same namespace._

=== Images Files ===

To include an image file, make sure it resides in the 'images/' directory relative to the document you're including it from.
Then go:

[source]
----
image::logo-standard.png[]
----

Which is rendered as:

image::logo-standard.png[]

Please note that the 'images/' directory is added automatically and not part of the link.

There are also global resources, residing in 'manual/src/resources', which will be copied to the root of the documentation.

== Code Snippets ==

=== Import from codebase ===
Most source code that is included in the documentation should be extract via +SNIPPET+ markers and then included in document with;

[source]
----
 [snippet,java]
 -----------
 source=tutorials/introduction/tenminutes/src/main/java/org/apache/zest/demo/tenminute/OrderEntity.java
 tag=mainClass
 -----------
----

The source file is relative to the SDK root, and the 'tag' is defined in the source file.
The above could be bringing in content that looks like;

[source]
----
package org.apache.zest.demo.tenminute;

import org.apache.zest.api.concern.Concerns;
import org.apache.zest.api.entity.EntityComposite;
import org.apache.zest.api.sideeffect.SideEffects;

// START SNIPPET: sideEffect
@SideEffects( MailNotifySideEffect.class )
// START SNIPPET: mainClass
@Concerns({PurchaseLimitConcern.class, InventoryConcern.class})
public interface OrderEntity
    extends Order, HasSequenceNumber, HasCustomer,
            HasLineItems, Confirmable, EntityComposite
{
// END SNIPPET: sideEffect
}
// END SNIPPET: mainClass
----

which will be rendered as;

[snippet,java]
-----------
source=tutorials/introduction/tenminutes/src/main/java/org/apache/zest/demo/tenminute/OrderEntity.java
tag=mainClass
-----------

Note that
1. The START and END doesn't need to be matching.
1. The AsciiDoc plugin will remove the 'START SNIPPET' and 'END SNIPPET' lines.
1. If you have more than one START/END section with the same tag, the plugin will insert a "[...snip...]" for the excluded lines.


=== Explicitly defined in the document ===

WARNING: Use this kind of code snippets as little as possible.
  They are well known to get out of sync with reality after a while.

This is how to do it:

[source]
----
 [source,java]
 ----
 HashMap<String,String> result = new HashMap<String,String>();
 for( String name : names )
 {
     if( !"".equals( name ) )
         result.put( name, value );
 }
 ----
----

Which is rendered as:

[source,java]
----
 HashMap<String,String> result = new HashMap<String,String>();
 for( String name : names )
 {
     if( !"".equals( name ) )
         result.put( name, value );
 }
----

=== Source code Highlighting ===
If there's no suitable syntax highlighter, just omit the language: +[source]+.

Currently the following syntax highlighters are enabled:

* Bash
* Groovy
* Java
* JavaScript
* Python
* Ruby
* Scala
* XML

For other highlighters we could add see http://alexgorbatchev.com/SyntaxHighlighter/manual/brushes/.


== Attributes ==

Common attributes you can use in documents:

* \{qi4j-revnumber} - rendered as "{qi4j-revnumber}"
* \{qi4j-importdir} - rendered as "{qi4j-importdir}"

These can substitute part of URLs that point to for example APIdocs or source code.


== Toolchain ==

Useful links when configuring the docbook toolchain:

* http://www.methods.co.nz/asciidoc
* http://powerman.name/doc/asciidoc
* alexgorbatchev.com/SyntaxHighlighter/manual/brushes/
* http://www.docbook.org/tdg/en/html/docbook.html
* http://www.sagehill.net/docbookxsl/index.html
* http://docbook.sourceforge.net/release/xsl/1.76.1/doc/html/index.html
* http://docbook.sourceforge.net/release/xsl/1.76.1/doc/fo/index.html