Update readme with metadata format details #6
Conversation
There was a problem hiding this comment.
The formatting is defaulting to paragraph flow, making it difficult to read the list of possible error types:
Similarly, the specific errors list are folded into one line, without punctuation:
Might be worthwhile to use a nested list on the specific types to force each returned message onto its own line. I recommend using grip to view the docs locally, with full formatting.
Content-wise, changes are solid. Once the formatting nits are cleaned up, good to go!
README.md
Outdated
|
|
||
| ### Devices | ||
|
|
||
| For all 5 devices described below, there are three generic errors that apply: |
There was a problem hiding this comment.
One more question, @emkll. The passage here states that "there are three generic errors that apply" but the succeeding list is five elements long. If I understand correctly, all five "generic" messages can be returned by any of the device type integrations (enumerated below).
If that's the case, perhaps we should say "For all device types (described in detail below), the following standard error types can be returned:". Then, below, instead of "The list of devices are as follows" should be changed to "The supported device types for export are as follows, including the possible errors specific to that device type:".
What do you think?
emkll
force-pushed
the
280-readme-export-format
branch
from
eb575b0 to
23e16cf
Compare
README.md
Outdated
| - `ERROR_PRINT` if there is an error printing | ||
|
|
||
|
|
||
| 5. `disk`: sends files to disk: |
There was a problem hiding this comment.
it would also be helpful to see the errors that can come up for the export disk method, such as: USB_BAD_PASSPHRASE and ERROR_USB_MOUNT
There was a problem hiding this comment.
(and ERROR_USB_WRITE)
There was a problem hiding this comment.
great point @creviera, added those error codes and their description
- Fix formatting - Reword device section - Add more error codes for `disk` export method
emkll
force-pushed
the
280-readme-export-format
branch
from
23e16cf to
b1a12d2
Compare
Tiny readability improvements, since we'll be referring back to this document frequently. Specifically: * use in-line for documenting file extension * greater indentation in sublists * use "definition list" formatting for metadata defns
Actually closes freedomofpress/securedrop-workstation#280