A guide to the NSX Docs
- 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.
- 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 README.md, which will result in it being located at the name of the folder; i.e. /baseComponents/README.md will become /base), 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 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.
An automatic link checker is present for all markdown files, and a build will fail if an invalid link is present, or if a .md file is not included in the "SUMMARY.md" directory. The link checker can be executed manually:
(the 'walk' module from the NPM is necessary for this script) Currently, the program does not indicate where exactly the errors occur. An explanation of the errors:
|Duplicate filename:||A file was declared two times in the SUMMARY file (usually due to movements/copy-paste)|
|Missing Filename:||A file was not declared in the SUMMARY file (if allowed, this would result in an uncompiled markdown file)|
|Duplicate file:||Something really went wrong, as most OS-es do not support this|
|Missing File:||A file was declared in the SUMMARY, but was not found. Either the file moved, or was deleted|
|Absolute link not found:||A file was not found, which was linked through an absolute link. Simply search the files for the link, and fix|
|Relative link not found:||A file was not found, which was linked through a relative link. Try searching for the filename|
A local copy can be hosted by running the run.sh script.