Files within the structure above can either be viewed on a local development server (generally to test the functionality of the site) or built to HTML and javascript files that can be uploaded and served from a webhost. One of the benefits of Static HTML is that there is no database component, so the files can be sent via FTP to a hosting service and the site just works. Alternaively, and this is something we still need to test, static html files can be added to a Sharepoint site, and then can be accessed by viewing the index.aspx file. Sharepoint will serve the html directly, with no additional hosting required. Details

Prior to building the site don't forget to update the Docs Version numbers in the docusaurus.config.js and package.json files.

Each of the commands below should be run from within the project directory.

Installation​

cd project-folder
yarn install

This command generates the files needed for Docusaurus to create both the development server an the build directory.

Local Development​

cd project-folder
yarn start

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

Build​

cd project-folder
yarn build

This command generates static content into the build directory and can be served using any static contents hosting service.

Password Protection​

So maaaaaybe there's a little issue with who actually owns the copyright to the source files used to generate this documentation. While it's under active development, we probably want to keep access restricted to just a handful of people. I went for the laziest possible option and simply encrypted the index page of the built site so that it requires a password to enter. Note that this is the only page that is encrypted right now. If you send someone any link other than the main index it's fully free and available out on the internet. If at a later point we determine we want to encrypt all of it, that is certainly possible, I just don't think it's worth the effort for our proof of concept.

index.html is encrypted with a tool called staticrypt. This has just been manually run on that file after the build process, and then the index_encrypted.html replaces index.html on the live site (renamed to index.html of course).

Ceres 6 is a complete rewrite of Ceres, and uses a completlely new web-based visual style. This means that nearly every screenshot in the Ceres 5 documentation is obsolete. In previous updates, even if the visual changes were minor, the screenshots were updated alongside a review of the documentation.

The Ceres 4 image above is nearly identical to the Ceres 5 image below.

Below is the batch selection screnshot for Ceres 6. It's clear that there is enough difference between Ceres 5 and Ceres 6 that new screenshots should be included.

In addition to new screenshots, the user interface has changed enough that some of the instructions included in previous sets of documentation are now less helpful. For example, the menu on the left side of the Role Center screen has now changed to one of three menus along the top of the screen. More confusingly, that menu changes depending on both the Role Center assigned to the user and the display options the user has selected. The menu is also now a horizontal list instead of a vertical one, meaning many options are nested. This means that orientation documentation is confusingly written, like this:

Agency Orders can be accessed by selecting “Search” from the Dynamics 365 Business Central Banner and entering “Agency Orders” in “Tell me what you want to do" then selecting “Agency Orders” from the results in the Go to Pages and Tasks section OR by selecting the “Agency Orders” menu action (if present) from your Role Center home page.

Umm... "if present?"

It turns out that "if present" is a recurring theme in Ceres 6. Its deep user customization features make navigation-related documentation difficult, and the screenshots unhelpful. In the above example, both the "Business Central Banner" and "if present" parts are not included in the screenshot, although for some Wye documentation the BC Banner has been (randomly) included.

Finally, Ceres 6 adds very few new foodbank specific features that were not present in Ceres 5. Any new features are more related to updates made to the Business Central 365 platform, and not to the Ceres customizations.

This ultimately leads to two questions:

1. Is it important to update all the screenshots to the new version? (yes)
2. How much does the documentation need to be updated to reflect navigation-related changes to the interface? Alternately, can all the navigation-related information be extracted to a "Getting Around in Ceres" document, which can be referenced rather than endlessly repeated?

Versioning in Docusaurus​

Docusaurus assumes that your screenshots don't all change between versions. The versioned_docs directory splits out markdown files into their own versioned subdirectory, but leaves any static files (like images) outside of the versioned subdirectory. When new versions are created, all current static files are copied into the versioned_docs/static subdirectory, overwriting what's already there. To keep Version 5 images distinct from Version 6 images, there are a couple of options:

1. Rename all the Ceres 6 images, and update all the Ceres 6 md files with the new filename (faster, sloppy)
2. Move Ceres 5 images to a new static directory and update all the md files with the new path (cleaner)
3. Move all images to versioned_docs/version-5/img/ and update all paths in all documents; do the same thing for C6 (cleanest, also images apparently aren't static :/ )

Missing WYE Ceres 6 Documentation​

Not all Ceres 5 documentation has been converted by WYE to Ceres 6. These fall into two categories: documentation that they never created in the first place, and documentation that was abandoned. In this repository, Ceres 6 versions of all those documents exist, but they will need to have their screenshots updated (and be reviewed for functionality).

Ceres 6 Documents that do not have a matching Wye Ceres 6 version have been added to the Cleanup Tasks list.

Many of the links in the related topics sections aren't connected yet - that's an ongoing task. The ones below reference documents that either don't exist or have been updated or renamed.

Old image linking format​

At some point in 2021 I changed the way images were linked. The earlier way is harder to read, and doesn't actually show the image if you're viewing the documentation directly in GitHub. This will need to be fixed in tandem with the Ceres 6 image updates, because the old method doesn't correctly find versioned images, e.g., it displays version 6 images for the verion 5 documentation.

Old: <img alt="Navigating to Agencies & Receivable Setup" src={useBaseUrl('img/agency-compliance/image2.png')} />

New: ![alt text](../docs/img/agency-credit-limits-and-credit-management/image2.png)

In VSCode, a list of ones to be fixed can be generated by searching all files for src={useBaseUrl

New image link format required​

• donation-order-overview
• account-schedules-overview
• bank-reconciliations
• cost-allocations
• gl-dimensions-and-dimension-values
• grants-overview
• year-end-closing-fiscal-year
• bin-overview
• item-charges-overview
• item-overview
• location-overview
• warehouse-activity-plan-WAP
• zone-overview
• user-setup-overview
• purchase-invoice-overview

Additional TODOs​

• Consider extracting stylesheet information from the Purpose section
• Consider adding Image Zoom Plugin
• Local Search dependency is temporarily different -- original maintainer has vanished. Keep tabs on this if local search breaks.
• Construct some higher level walkthroughs, that reference individual help files, e.g., Invoicing and Paying Vendors.
• Item Data Management appears to be missing for Ceres 5

Ceres 6 Documentation that needs screenshots​

Some Ceres 6 documentation was not updated by Wye with new screenshots. The list of documents that need updated screenshots for Ceres 6 is below:

• Agency Express Orders Lost Product Checklist
• Document Sending Profile
• Parent Agency Overview
• Quantity Available Performance Analyzer
• Donation Order Overview
• Donor Overview (last screenshot)
• Donor Preferred Pickup Days and Hours (last screenshot)
• Food Drive Overview (one error message)
• Parent Donor Overview
• Top Donor Report
• Accounts Payable ACH Processing
• Bank Reconciliations
• Chart of Accounts Overview (last screenshot)
• Cost Allocations
• Creating and Opening Accounting Periods
• Fixed Assets Setup
• General Journal Overview
• G/L Dimension Reporting
• GL Dimensions and Dimension Values
• GL Self Balancing Overview
• Grants Overview
• Processing 1099s
• Reason Codes Mandatory Overview
• Voiding an AP Check
• Year End - Closing Fiscal Year
• Allocated Agency Orders Overview
• Full Pallet Order Handling
• Inventory Analysis Report
• Inventory Lot Costing and Pricing
• Inventory Movement Worksheet Templates
• Item Charges Overview
• (NOTE: The following three could be combined into an Item Journal doc...)
• Item Journal - Adjusting Quantities
• Item Journal - Repack and Reclass
• Item Journal - Suggest Lots
• Item Overview
• Item Reclass Journal Overview
• Kitting Overview
• Location Overview
• Meal Connect Implementation Guide
• Meal Connect Integration User Guide and Error Handling
• Meal Connect Setup Guide
• Order Staging
• Pre-Orders and Standing Orders
• Roadnet Agency Order Exports
• Roadnet Donation Pickup Exports
• Roadnet Transfer Order Exports
• Transfer Order Overview
• UNC Coding and Relation to FA Reporting
• Voxware Overview and Integration
• Warehouse Activity Plan - WAP
• Warehouse Activity Plan and Default Bin Picking
• Warehouse ADCS Barcode Processing
• Warehouse Pallets and Lots
• Warehouse Put-Away Overview
• Warehouse Receipting
• Zone Overview
• Mass Emails (probably needs addional update with EoL for SMTP)
• My Jet Reports
• NY HPNAP Reporting
• Order Handling Groups and Order Routing Groups
• Quick Access Guide (needs refresh for Ceres 6)
• Receipts and Distribution Report with XML Export
• Remote Application 2.0 Web Access Login Procedure
• Standard Text Codes
• Supplemental Addresses
• User Setup Overview
• Document Management Record Links (needs refresh for Ceres 6)
• Item Purchase Replenishment (review. Not sure this is functional)
• Parent Vendor Overview
• Processing AP Checks
• Purchase Credit Memo Overview
• Purchase Invoice Overview
• Purchase Order Overview
• Purchase Orders and Invoices with Grants
• Purchase Requisition Worksheet
• Purchase Return Order Overview
• Vendor Item Cross References and Prices
• Vendor Order Addresses
• Vendor Overview
• Vendor Purchases via Credit Card

Other missing topics​

This stuff has no documentation at all:

• Adding memo lines to Agency Invoices (Modify Statement/Report Comment)

Indentation​

Some of the existing documentation relies on nested indentation to separate out descriptions of things. For example, in Location Overview, in the Bin Policies FastTab section, the main title and first sentence are against the left margin. The following field descriptions are indented one tab. The Use WAP Suggestion field has options, so the options are indented by two tabs. One of the options, Prompt for Suggestion Handling has two options and a cancel button in the resulting dialog box. These sub-options are indented by three tabs.

Markdown doesn't really do indentation. Workarounds exist, like using inline HTML, JSX and other things, but none of them are particularly intuitive when converting the docs. Each of these workarounds also adds extra time in the document conversion stage.

Some other options

Images​

The images in the current Word-based documentation are pasted directly in each document, in line with the text and at various sizes. With each iteration of Ceres, the images in the documents are manually updated to reflect the newer version. Because Word is not desktop publishing software, the images do not require names and can be quickly resized by just dragging corners. This means that all of the images in the current version of the documentation are all different sizes. See the images here for an example. Notice that the main screen image and the batch selection screen image are wildly different resolutions.

In a static HTML site, images are stored in a separate folder outside of the text portion of the document. Because we want the images to appear in-line with the text, the image is referenced by a link to that separate folder. Within its .docx file container Word is actually storing the image in a separate images folder, too. So while we can extract the images easily, they get names like image15.png, which makes it difficult to know whether the correct image is linked.

If documentation is created with a static HTML format in mind (rather than in Word) it would be helpful to require a consistent image resolution/size and a consistent naming scheme. Both would require an agreed upon set of standards before proceeding.

Tables​

Tables in Markdown are very simplified and are unable to understand spanned or merged columns or rows. For example, the following table from the WAP document is harder to read than the one in the original Word document. It could, however be presented in a non-table format that would also make sense so it may not be an issue. It could also be included as an image (see the shortcuts section of the Purpose document for a Drawio example that could work.)

Original file:

Markdown table:

Documentation​

This is to help document what I’ve done to generate the proposed Ceres 6 documentation site. It’s mostly just process notes and will frequently point to documentation elsewhere. It’s very likely that there are more effective ways to do this – this is just what I’ve been doing. For example, I started working in Visual Studio Code to create the markdown files and sync with GitHub, but VS Code may or may not be the best tool for this purpose.

Project​

The current Ceres help system consists of dozens of Word documents. There are good historical reasons for this, including (among other things) maintaining the ability of food bank users to download and modify them to reflect their own internal business rules and workflows. When Ceres is upgraded, however, the process of revising the documentation for the new version is unwieldy and takes a very long time.

Part of the difficulty in updating documentation is inherent in Word itself. Each document is completely independent, so extra time is needed to check pagination, formatting, indentation, typeface, and the table of contents. And as the documents are each tied to a single process, page, concept or workflow, there is necessarily a significant amount of both overlap between documents and references to other related documents. Word does have the ability to link between documents, but these links all break when the Word documents change location.

The document review process in Word is not designed to process the comments, updates, and suggestions of more than a handful of people. Emailing zip files of document bundles back and forth and using track changes is not only inefficient, but it also lacks any process for explaining why a particular update or change was made, and it’s impossible to roll a particular document back to an arbitrary version unless that version was explicitly saved somewhere.

The current Word documentation is also static. No user feedback is ever taken into consideration when updating the documentation, so if steps are unclear or misleading, they stay that way forever.

The purpose of this project is to identify a set of tools that can address some of the shortcomings of a Word-based documentation system, while also maintaining the ability of food bank users to copy, tweak and remix the documentation for their own purpose. Ideally, the new system will also provide some additional usability, and ultimately take significantly less time and effort to maintain.

Tools and Process​

As mentioned above, this is a set of tools that I’ve identified after spending some time researching current documentation systems. The top priorities in my search were:

• Formatting applied by an overall stylesheet, not per document
• An embedded version control process for making updates to the documentation
• Food banks can easily take a copy of a document to modify for their own purposes
• Ability to document more than one Ceres version
• Hyperlinks available
• Searchable within and across all documents
• Uses readily available, inexpensive tools, very low maintenance expense
• Uses existing documentation as source files
• A process for user feedback on the documentation

For this set of priorities, I’ve identified the following solution:

• Documentation written in markdown
  • (Partially) converted from .docx to .md using Pandoc
  • Using Visual Studio Code as the IDE
• Markdown files stored in a Git version control system hosted on GitHub
• Documentation converted to static HTML using Docusaurus v3
• A package manager for Docusaurus, including Node.js and Yarn
• Static HTML can be served on any website

Demo Structure​

The demo was built with the Docusaurus v2 “classic” template (now updated to v3), which creates a project structure like this:

my-website
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Documentation files, written in markdown, live in the docs folder. Images for the documentation live in subfolders beneath the static/img folder. Other non-documentation pages (also in markdown) can be placed in the blog folder (along with associated images in the 'static/img' subfolder). The sidebars.js file is a javascript file that can be modified to create categories of document and arrange the documents within those categories. The docusaurus.config.js file contains part of the page layout and plugins for the site. The src/pages/index.js file contains details on the initial landing page.

Generating the Static HTML Site​

See the Build Instructions document.

Markdown​

The docs themselves are written in markdown, a human-readable, text-based formatting language. Docusaurus uses the MDX markdown processor to convert markdown into HTML. There are also a few extensions to markdown, which allow callouts and other more complicated formatting when necessary.

Images​

Markdown is text-based, and similarly to HTML, images must be stored separately from the markdown source. In Docusaurus, the static HTML that is generated directly copies the contents of the static/img folder, so images need to be linked from that location. For ease of conversion to other hosting locations, we’re using the useBaseUrl function in Docusaurus. In addition to images, any other files can be housed in the static/img folder. This makes it possible to link things like Excel import templates saved within the documentation. See this section of the Vendor Purchases Via Credit Card documentation.

It also supports animated gifs. Try that in Word...

Conversion of Word to Markdown​

A .docx file is a container that holds a bunch of information, including text, formatting, and images. In our documentation site, we want these elements separated. Unfortunately, that means you can’t just export existing Word docs to markdown. There may be faster or more efficient ways to do this, but I used a command-line conversion tool called Pandoc, which can extract the text and some of the formatting from a .docx file to a .md file. And since the .docx file container is just a zip compressed file, it’s possible to extract the images all at once, and with trackable filenames.

Pandoc​

To convert AccountSchedulesOverview.docx to a .md file with the closest appropriate markup, use the following command. It’s going from docx format to github flavored markup, output to account-schedules-overview.md.

pandoc --shift-heading-level-by=1 --wrap=none --extract-media=. -f docx -t gfm -o inventory-process-flows.md InventoryProcessFlows.docx

• The wrap flag is set to none so that each paragraph lives on its own line in the markdown file. This speeds up input and editing significantly, as you no longer need to clean up all the arbitrary blockquotes.
• The extract-media flag gets the images from the media folder within the .docx document.
• The shift-heading-level-by flag moves all headings down by one, as the first heading (h1) is always the title in markdown.

Transfer .md File to Documentation Filesystem​

The .md file is copied into the filesystem in the docs/xxx folder, where xxx is the category for the documentation. For example, account-schedules-overview.md is placed in the docs/financial-management folder. The sidebar is automatically generated based upon what folder the file goes into. (This may be updated as the sidebar gets more complicated.)

Required Edits​

Once in markdown, the file will still need to be tweaked to be consistent with markdown syntax, our desired formatting, and some Docusaurus specific requirements. A linter is available for VSCode to help with syntax and prevent unintentional formatting errors. The manual modifications required for account-schedules-overview.md to be complete were:

• Add front matter to the top of the file, e.g., the document ID, title, sidebar label, slug, and some static javascript to allow easier maintenance of image paths
• Remove the “Purpose” header and table of contents
• Fix markdown syntax warnings
  • Move all headings down one level as there should only be one top-level heading in a document, and that’s the title. (fixed with the shift-heading-level-by flag in Pandoc)
  • Correct all the indentations interpreted as block quotes (partially fixed with the wrap flag in Pandoc)
  • Remove extra spaces and lines
• Turn the Financial Period Description variables into an unordered list (instead of tabbed columns)
• Surround entry snippets, like the date range entry 07/01/14..06/30/15 into code to make it easier to read
• Pull out notes to admonitions
• Change fragile Unicode --> (and broken á) to ▸
• Remove extraneous escape code before dollar signs.
• Extract images from media folder of docx zip file and put them in newly created \static\img\account-schedules-overview folder. (Extraction is now automated using the Pandoc extract-media flag).
  • Occasionally, images are accidentally duplicated within the Word document and need to be deleted, or images were anchored in the Word document out of order, so need to be manually reorderd. In a few cases, images in Word were pasted from email documents generating .eml images, which need to be converted to a normal fomat.
• Replace markdown image links with HTML and add alt-text for each (or use markdown image links, which are slightly faster to enter) (11/23/23: Markdown image links are now preferred. See cleanup tasks doc.)
  • Some images do not include attention indicators in the image file (the red rounded rectangles) as they were added as shapes in Word. This may be less important for Ceres 6, as most of the screenshots will be new.
• Link to the documents in the Related Topics section. (10/7/22: the Slug header item allows you to ignore all path information now)
• Add the document to the correct category in the sidebar (10/7/22: no longer necessary, as the sidebar is now automatically generated. See TODO sidebar section.)

The process typically takes between 5 and 15 minutes per document (learning curve not included). For example, the 48-page Warehouse ADCS Barcode Processing document was converted in 16 minutes.

Shortcuts​

• Find and replace can be used to correctly format numbered lists. (find: a period and two spaces; replace: a period and one space)
• VSCode allows Regular Expressions in Find and Replace, so image link text can quickly be edited by replacing <img src="./media/ with ![alt text](../img/title-of-document/ and then " st.* with ).
• VSCode has an extension that allows drawio diagrams to be created and edited directly in VSCode and autosaved/embedded as an image file. See below (from the Kitting Overview document.)

GitHub and Version Control​

The ability to keep both the documents and the framework in a GitHub repository that includes version control helps in a few ways:

• The entire framework can be cloned so that a food bank could build a customized internal version that works the same way
• The main branch is the single source of truth for the documentation
• Documentation users can log issues to track todos, bugs and requests. Documentation maintainers can categorize and respond to issues
• Both maintainers and users can create pull requests, which allows anyone to collaborate on making the documentation (or the framework) better. Only a select set of maintainers can ever merge pull requests into the main branch, and it's easy to see and understand comparisons between the original files and the suggested updates.

TODO​

• Sidebars need to better reflect the documentation categorization and heirarchy currently found in Hungernet.
• Many non-documentation things are not here, e.g., webinars, etc. It would be especially helpful to include a demo of particular features (excerpted from User Groups) augmenting the purpose section of the documents. This would require either DOCID on Hungernet or the individual snippets would be uploaded to a private page on YouTube or something. Including video files in the documentation source is probably not a great idea.
• Sample task walkthroughs should be created, similar to some of the SJC "how do I" reference documents.