Documentation Template for Steps and Job Entries
WORK IN PROGRESS (see also Pentaho internal DOC-1940)
Notes for the documentation template: Each section contains a description about its purpose, if it is mandatory or optional and an example that begins or contains the words "Lorem ipsum".
Description
Required section. The description should follow the title directly without a heading. Use this section to provide a general, high-level overview about the step or job entry. For example:
"The Lorem ipsum step (or job entry) is a placeholder text commonly used to demonstrate the graphic elements of a document or visual presentation. By replacing the distraction of meaningful content with filler text of scrambled Latin it allows viewers to focus on graphical elements such as font, typography, and layout."
It is recommended that a screenshot is included here.
Special notes are optional elements. Notes should highlight general items that need attention. If a note is more specific to a subsection or other section, it should be placed in the section they belong to. Use this style for all notes.
This section may include the following subsections:
Context
Required section. Use this section to describe the context surrounding when this step or job entry is used. It is also possible to link to another page which has workflows and tasks.
The context should include information about when and why you would use this step or entry, as well as additional information to help the user understand the benefits of the step or entry in a typical workflow.
Prerequisites
Optional section. Use when prerequisites need to be met and/or checked.
Installation
Optional section. Use when installation tasks need to be performed.
Configuration
Optional section. Use when configuration tasks need to be performed.
Options
Required section. This section describes the Options and Description for each property of the step or job entry using a table. When multiple tabs are included in a dialog box, use subsections titled by tab such as "Sample 1 Tab" and "Sample 2 Tab". Optionally, you can preface the table with information, if needed.
TBD: 1) Omit not needed information: e.g. step name (should be describes not within each step/job entry but at the beginning) 2) Should we omit other obvious properties? 3) Should we omit the recurring information in field tables like: field name, type, length, precision etc. ?)
It is recommended that a screenshot of the tab is included above the table.
Option |
Description |
|---|---|
Option 1 |
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam. |
Option 2 |
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam
|
Sample 1 Tab
It is recommended that a screenshot of the tab is included above the table.
Option |
Description |
|---|---|
Option 1 |
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam. |
Option 2 |
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam |
Sample 2 Tab
It is recommended that a screenshot of the tab is included above the table.
Option |
Description |
|---|---|
Option 1 |
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam. |
Option 2 |
Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam |
Example
Required section. Describe at least one example, link to another page, or reference a sample within the PDI distribution.
Samples within the PDI distribution can be found here: data-integration/samples/transformations/Aggregate - basics.ktr
When referring out to another page, place the link in a sentence: "A list of example lorem ipsum text can be found here: http://en.wikipedia.org/wiki/Lorem_ipsum"
Sample(s)
Optional section. This section is similar to the Example section except that it exclusively refers to the samples with the PDI distribution. Samples within the PDI distribution can be found here: data-integration/samples/transformations/Aggregate - basics.ktr. Even if you use an example in the above section, if other samples exist for the step or entry, you should refer users to those samples.
Reference Information
Optional section. Use this section to list internal or external links, such as step-by-step and workflow topics, related to this step/entry.
"For workflow and use case information, see Lorem ipsum: http://en.wikipedia.org/wiki/Lorem_ipsum."
Technical Information
Optional section. Use this section when to provide technical documentation to developers. For example, you can include a link to the source code, special topics for developers, or links to the source code or Javadoc.
"Source code for Lorem ipsum can be found here: http://en.wikipedia.org/wiki/Lorem_ipsum."