Skip to content

FlyByWire Documentation Project

- Documentation Project Github

Background

The FlyByWire Documentation Project aims to provide all necessary information and documentation to successfully install and use the FlyByWire A32NX aircraft in Microsoft Flight Simulator.

For this we provide documentation about the A32NX add-on itself but also valuable additional documentation on how to fly an airliner on Microsoft Flight Simulator in general and even some specific A320neo documentation for the more involved user.

We apply very high standards to quality and accuracy of our documentation so that it is easy to read and understand but also as correct as possible. Therefore we have a strict quality process and everything is reviewed by several users and real pilots from our team.

How to Contribute

Contacts for FlyByWire Documentation Team

If you have questions or suggestions, or if you want to contribute to the FlyByWire Documentation project, please contact us on Discord:

- Discord Link

  • Valastiri#8902
  • Cdr_Maverick#6475

Required Tools

To participate in the FlyByWire Documentation Project you need to have following tools installed:

  • Github account and Git (Github Quickstart)
  • Python (Python Downloads)
  • Install the following Python based tools (see install command below):
    • MkDocs (MkDocs)
    • mkdocs-awesome-pages-plugin
    • mkdocs-git-revision-date-localized-plugin
    • mkdocs-material
    • mkdocs-redirects

  • Install with this single line command:

    pip install -r requirements.txt

  • Editor / IDE:

Process

Preview your Local Clone

  • Fork the - Documentation Project Github (How to fork a repository).
  • Create a local clone (How to cloning your forked repository).
  • Checkout the "primary" branch - this is the main branch of the current FlyByWire Documentation Project.

  • In a command line terminal go to the cloned repository folder and start mkdocs.exe serve to start the local preview server.

    This should look like this:

    > mkdocs.exe serve
INFO     -  Building documentation...
INFO     -  Cleaning site directory
INFO     -  Documentation built in 4.03 seconds
INFO     -  [12:05:30] Serving on http://127.0.0.1:8000/

Faster Preview Server

You can opt to use a faster instance of the developer server by invoking the flag --dirtyreload. This just checks for any markdown that has changed since the HTML was rendered and will reconstruct any relevant pages only rather than rebuilding the entire website.

mkdocs.exe server --dirtyreload

Navigation and new internal links may not get updated on other pages while using --dirtyreload. Verify links using the standard serve or build command.

  • You can now browse the current checked out branch in a browser at this address: http://127.0.0.1:8000/. The site renders every time you save any filename.md you are working on.

  • Optional: Build static site locally for testing:

    mkdocs build --clean --no-directory-urls
    • The site will be built locally under /site on in your local repo for user testing. Openindex.html in the root of /site to preview.
    • Note: --no-directory-urls allows usage of reference links when browsing the locally built site. Prevents having to find each index.html related to every filename.md to preview the relevant page.

Make Changes or Additions to the Documentation

  • Create a new branch based of branch "primary" (might differ for certain sub-projects) and checkout this new branch. Give a short but meaningful name to the branch.
  • Make initial changes on your local branch.
  • Create a Draft Pull Request (aka PR) early to let people know what you are working on.
    • Explain in the PR Description what you are changing/adding and how people should review your changes.
  • Work on your changes locally, preview constantly and push your changes regularly to get a preview deployment for others to give feedback.
    • Every time you push changes to your PR a preview is generated with a URL. You can share this link in Discord for the team to provide feedback easily. The URL (by the vercel bot) is visible as a comment on your PR github page.
  • When finished, push your final changes to the PR, update the PR description if required and mark it "Ready for Review".
  • Someone from the documentation team will review your changes, give feedback, potentially ask for changes, and eventually approve and merge your changes.

How to Write Documentation for FlyByWire

Technical How-To

  • You can edit existing pages simply by editing an existing pagename.md.
  • To create a page simply create a new file "pagename.md" in an appropriate folder and start writing your documentation. Best practices it to look at other pages regarding the general structure (Headings, Material for MkDocs features, etc.).
  • Create the page in the navigation folder you feel this page belongs to. The Documentation Team will be happy to support you with the best location and also how to create a navigation to your page.
  • During the PR Review the page still can be moved and navigation can be changed/added. So don't worry too much about it and focus on the content for your page.
  • Add images to the section's asset folder. Consider creating a folder for your page when using several images.
  • Although the FlyByWire Documentation Team will take care of navigation it might still be of interest how the navigation is done. This is well explained on the mkdocs-awesome-pages-plugin's README on their Github

Embedding YouTube Videos

We have included the plugin mkdocs-video to streamline adding YouTube embeds into documentation. This removes the necessity to inline <iframe> information within documentation pages.

The plugin uses the markdown image syntax with a custom marker defined in mkdocs.yml: video-embed.

Sample YouTube Embed Code
![video-embed](https://www.youtube.com/embed/3i1FaGKOwII)

Tips to Work Effectively with mkdocs (Change, Previews, etc.)

  • Have your editor and browser preview side-by-side on your screen.
  • Every time you save your file the "mkdocs serve" should make your browser reload and you can preview your changes directly.
  • Start with the structure of your documentation page. E.g. headlines first and maybe notes below the headlines of what the section should cover. Build up your page from there.
  • How to do:
    • Links: [Link-Text](https://www.target.domain/page)
      • internal links need a relative path to the .md file
      • add {target=new} to external links
      • look into existing pages for examples
    • Other Material for MkDocs features

Writing Good Documentation

  • Write documentation professionally and clearly.
  • Write for the targeted audience (Sim Beginner, Sim Veteran, Developers, etc.) and don't assume too much pre-knowledge on the reader's side.
  • Use the full availability of features baked into Material for MkDocs to create readable and well formatted guides.
  • Add illustrations where appropriate. Make sure you optimize images to be as small as possible (resize to their actually used size and use JPG Compression (50% is mostly ok).
  • Ensure relevant filenames are web friendly slugs.
  • Don't hesitate to get feedback from the FlyByWire Documentation Team early and often.
  • Proofread your work carefully before marking "Ready for Review".

Ideas and Issues

Please use Github's Issue tracker for any documentation request or issues you might have encountered.

- Documentation Project Issues

Last update: August 27, 2022