Challenges
Challenges
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.
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:
| Option 1 | Option 2 | Option 3 | |||||
|---|---|---|---|---|---|---|---|
| Must select 1 | Must select 1 | Optional: Either, both or none | |||||
| Only one selection allowed | Only one selection allowed | ||||||
| Empty Bin | Not Full w/Same Item | By Row No. | By Bin Ranking | Fixed Bin | Last-Used Pick Bin | Same Zone | Same Bin Class |