About

Guidelines

  • This documentation is public-facing. Do not include confidential information.
  • If you’re not sure about the quality, write it anyway, but mark it with a TODO so that it can be reviewed later (and everyone knows that this is preliminary). Bad documentation is, at this point, better than no documentation.
  • If unsure about the location of the article, put it in the wisdom folder.
  • Found something that is wrong or can be written better? Simply edit, and fix it if you know the better answer, or add a TODO to mark the issue.

Engine

The documentation is built with Jekyll.

Jekyll is based on Ruby. So if you wish to build it locally you will have to install Ruby (follow instructions on Jekyll website).

We are using a variant on the Docsy Theme.

There are a few differences with Gitbook:

  • There is no SUMMARY file that needs to be kept in sync. Just drop your article in the _docs directory (and preferably link to it from another page).
  • The root articles for a directory are named index.md instead of README.md.
  • Absolute links need to be prefixed with ``
  • Links should point to the url, not the .md file

Main structure

Most articles are placed under the _docs directory.

  • The guides: These guides are the main entry point into the documentation. They follow three levels: analyst, application developer and expander developer. These levels are correspondent to the three roles within NSX. When writing guides in this section, never write something again that is already written in the architecture or tools sections. Instead, link ([text](link)) to the file.
    • Analyst guides (level 1): working with the prime radiant and NS modeler, and understanding the meta model.
    • Application Development guides (level 2): writing custom integrations, working with the databases. Should have an understanding of what the expansion process generates, but not how it works.
    • Expander Development guides (level 3): The full insight of the application, into the smallest details. Each artifact, injection, option and more should be listed
    • NS Wisdom: Articles which do not fit elsewhere in the other guides

The guides do not intrinsically posses any information directly, but rather reference the architecture and tools sections. These sections should be written with the principles of NS theory in mind. Therefore, each file should only tackle a single aspect. The linking of these aspects is handled in the guides section. Additionally, the information should be divided into the three levels for each element. This avoids an information overload when an article is referenced from a level 1 or level 2 guide.

  • Component (The meta model): This is where most of the documentation resides. The structure is somewhat similar to the structure as seen in the Prime Radiant. Each meta element has a folder with a similar structure:
    • The main article (called index.md, which will result in it being located at the name of the folder; i.e. /data/index.md will become /data), containing a short description, and a list of the attributes of the element.
    • Child elements, or other concepts which are related to the element should have their own article. E.g. the data element folder has a sub-folder for field, but also an article about data element types.
    • Options: Every option applicable to the data element.
    • Expansion Artifacts: Every element expands into a number of artifacts. Here, these artifacts are documented. This documentation is structured according to the six layers.
  • Release Notes: The release notes, which link to new information. These links should be bidirectional, i.e. if a feature is available from a certain release, it should be mentioned in the relevant article.
  • NS Tools:: Prime radiant, NS modeler, and the technical information for the expanders should go here
  • Todos: An automatically updated list of the todos in the documentation. This list is automatically generated whenever a new build is put live. In order to add a todo, add --**TODO** todo message-- anywhere in a file. Empty files are also marked as todos. If a todo should be empty, the todo can also be put in a comment: <!--**TODO** todo message-->.

Editing

Editing can be done either by cloning the repository locally, or by clicking the edit button on a page, and editing and committing the file on bitbucket itself.

As mentioned above. the --**TODO** todo message-- tag is available for marking work in progress or for indicating an issue to be fixed by someone else.

The dir_checker.js

The sidebar menu is populated with the _data/toc.yml file. This menu is visible on each page and so should be kept succinct.