Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
273 lines (190 sloc) 9.48 KB

Tutorial Contribution Guidelines

The Apache NetBeans Tutorials were included in the third donation from Oracle to the Apache Software Foundation. Many of these tutorials need to be reviewed. Everybody can help out in the review process. All you need is a web browser, a GitHub account and a basic knowledge of AsciiDoc.

This page describes some tips, tricks and conventions for reviewing tutorials for Apache NetBeans.

The NetBeans Web Site

The NetBeans website is written mainly in AsciiDoc, a way of creating technical components using plain text files.

We then generate HTML for the web using Groovy Server Page templates (these live in https://github.com/apache/incubator-netbeans-website/tree/master/netbeans.apache.org/src/content/templates ). These templates (and some other stuff like SCSS) are responsible for the layout of the web pages.

Note
The generated HTML is responsive, this is, it can be correctly visualized in mobile phones.

Direct editing in GitHub

All web pages can be edited directly in GitHub. To do so follow these instructions:

  1. Click the "See this page in GitHub" link at the bottom of any page.

contributing link
Figure 1. Click the 'See this page in GitHub' link to edit a page
  1. You will then be redirected to GitHub. Once there click the "Edit this file" button.

contributing button
Figure 2. Edit button in GitHub

If you don’t have edit permissions you always can clone the website repository in GitHub and then edit the file in your own clone, and then submit that as a Pull Request against the main Apache Repository.

AsciiDoc Conventions in Apache NetBeans

License Header

All .asciidoc pages must have a license header stating the Apache License and the Apache Software Foundation ownership. The Apache license header is included as an asciidoc comment, like so:

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

The title

All tutorials must start with a "Level 0" title with a single equal sign. This will be the title of the page. You write a title like so:

= This is a title

It is an error if there’s any content before the level 0 title (but for comments). If you see any content above the title then please move it below the title (that’s called the "AsciiDoc Preamble").

Metadata

Immediately after the level 0 title, we add the metadata of the page, all the "jbake-" entries are mandatory. Some others are commented below:

:jbake-type: tutorial
:jbake-tags: tutorials
:jbake-status: published
:reviewed: 2019-01-25
:syntax: true
:source-highlighter: pygments
:toc: left
:toc-title:
:icons: font
:description: NetBeans IDE Java Quick Start Tutorial - Apache NetBeans
:keywords: Apache NetBeans, Tutorials, NetBeans IDE Java Quick Start Tutorial

This is a small description of the metadata:

  • reviewed: set this to the date the tutorial was reviewed, for instance, 2019-01-25.

  • jbake-type: use tutorial for tutorial pages, wiki for wiki pages, page for simple pages.

  • jbake-tags: use tutorials for tutorials, feel free to any tags of your liking (we should formalize this).

  • jbake-status: always set it to published

  • Set syntax to true if this page contains source code that has to be syntax-highlighted. Please also add source-highlighter to pygments.

  • toc Set always to left.

  • toc-title Leave empty.

  • icons Set to font for adding support for FontAwesome icons.

  • description: set to something that describes the page. This is used for SEO.

  • keywords: keywords describing the page. This is used for SEO.

The Content

Write the rest of the page using plain AsciiDoc. See the AsciiDoctor Writer’s Guide for more information https://asciidoctor.org/docs/asciidoc-writers-guide/

You can structure the content using sections. Start each section with a level 1 header, that must have at least two equal signs (but can have more for subsections), like so:

== This is a section header

Some content here

=== This is a subsection

Some more stuff here
Tip
In general we should make the tutorials be less wordy, less long paragraphs. Special Constructs and Best Practices.

Inline screenshots and images

Images related to a webpage are usually included in a images/ subdirectory close to the webpage.

Screenshots should be at least 640px wide?? (what’s a good size for retina images?). PNG is preferred (isn’t it?)

Images in a table should be inlined, i.e., using the single colon image construct, like so:

image:images/image.png[]

Block images and screenshots

Block images are inserted using the image:: AsciiDoc construct, this is, with two colons. These take a paragraph of their own. Example:

image::images/image.png[title="This is the image caption"]
Note
Note the two colons for block images, and a single colon for inlined (in the paragraph) images.

Clickable screenshots

Clickable screenshots are generated using a "[.feature]" tag above a paragraph that contains the image. This allows us to have a small image (the focuses on a part of the screenshot) that the user can click to see a larger image. The AsciiDoc construct for these is like so:

[.feature]
--
image::images/the-title-of-the-image-small.png[role="left", title="Click to enlarge", link="images/the-title-of-the-image-big.png"]
--
Tip
Be sure to add a newline before the [.feature] tag.

Youtube videos

Use the "video" asciidoc macro to embed youtube videos, like so:

video::the-youtube-video-identifier[youtube, title="The title"]

where "the-youtube-video-identifier" is the id of the youtube video, for instance O8cwpEY1OAQ is the identifier for https://www.youtube.com/embed/O8cwpEY1OAQ

Source code

Use the plain asciidoc construct for source code excerpts (that is, four slashes). Please the the "lang" attribute accordingly, for instance, for Java:

 [source,java]
 ----
 System.out.println("Hello, world");
 ----

Other languages are html, xml, javascript, php, python, ruby. Remember to use the :syntax: true atribute in the metadata so that syntax highlighting works.

Numbered lists

Numbered lists that have in-between paragraphs often restart numbering. So, for instance, you have item 1, item 2, then a paragraph and then the next item starts again at 1

Remember that you can tell asciidoc to start a numbered list on a certain number using the "start" tag, like so:

1. This is the first item
2. This is the second item

Now we have a paragraph here, or an image or whatever

[start=3]
3. This is the third item

Admonitions (notes, tips)

Use NOTE: and TIP: for admonitions. These must be in capital letters, without any asterkisks around them:

NOTE: This is a note

If you use these admonitions be sure to add the

:icons: font

on the metadata of the page, so that admonitions have proper icons.

Icons

To use font awesome icons in your webpage include the :icons: font in the metadata of the page.

Then you can reference an icon using the name of the icon in the asciidoc icon macro, like so:

.icon:users[]

for a list of icons see https://fontawesome.com/icons?d=gallery

New features

If you need to include a new feature in the page then please request for it in our Dev Mailing List.