Docs 2 Design user guide

Docs 2 Design (D2D) is an Adobe XD plugin designed to extract your XD project text to standard editing environments, and then update it in place back in your XD project, once it’s been edited. It gives you a lot of control over–and insight into–this process. But, at heart, it’s very simple.

Let’s run through an example of using it in the most straightforward way possible, once you’ve got it installed in XD (versions 29 or later).

  • Select an artboard.

  • Choose the All operation scope in Artboards.

  • Make sure File / Sheet (the default) is chosen in Channel / Format.

  • Choose Extract All… to create an Excel spreadsheet file with all your project’s text content. (We call this a “snapshot,” a capture of the state of your artboard text at a point in time.)

  • Open that snapshot file with Excel or your favorite spreadsheet application. You’ll see one sheet per artboard, with all the text in one column named Base, one row per text item in the artboard. Edit any or all of those text items–for example, turn “lorem ipsum” text into actual text. Save the spreadsheet.

  • You’ll see D2D noting the file has been updated, in the Channel notes.

  • Choose Update All Artboards to pull in any changes from the spreadsheet into your document.

That’s it! D2D gets your text content out (“extracts” it) into familiar content editing tools, and then lets you bring it back in (“updates” it), and then helps you understand what was changed in the update. There are a lot more details that could be involved, but at its simplest, that’s the idea.

(Note that we’re planning on optionally including a snapshot of each artboard in the spreadsheet, with each text item visually numbered, so you can see each text item in context.)

Or, for a translation project, try this.

  • Select an artboard to enable D2D (this is always required for extract / update / variant switching, given the way that XD works).

  • With All selected in Artboards, open the Variants sub-panel.

  • In the Variants sub-panel, click New once, and then change the default Variant 1 name to French by editing the name and pressing Rename. Click New again, and again rename the new variant to German. (You can close the Variants sub-panel for now.)

  • Choose Extract All… and create an Excel snapshot file.

  • Open the snapshot file in Excel, and now you’ll see three content columns in each artboard’s sheet: Base, French, and German. The latter two will be empty, since you haven’t done anything with these variants yet.

  • Provide appropriate French and German translations in the corresponding columns for at least some of the base text, perhaps by sending it to a professional translation service, or by using Google auto-translate on the text snippets.

  • Choose Update All Artboards (with the snapshot file still open; if it’s not open then choose Update All Artboards… and select the updated snapshot file).

  • In the Variants sub-panel, you can now select Base to see the original text, French to see any French language translations made, and German ditto.

Of course, there’s a lot more detail and a lot more control possible that we’ll go over in the sections below. First, we’ll cover some overall concepts.

Snapshots

  • D2D’s snapshots should generally be considered highly ephemeral, to be created by extraction, edited externally, used to update the XD document whence they were extracted (perhaps over a time as more edits are made), and then discarded.

  • Snapshots aren’t meant as any kind of long-term storage or reference, though of course, one could save a snapshot of the text state of a document this way.

  • Snapshots are completely specific to the document they were extracted from, and can’t be used with any other document.

  • If you save an XD document under another name, then the new document will need its own set of snapshots to be made; snapshots made under the old name won’t work with the new.

Variants

“Variants” is the term we use for alternate versions of your artboard text content, whether it be different languages, different sets of wording alternatives proposed by your stakeholders, “lorem ipsum” placeholder text vs “real” text, etc.

By default, you have just one base variant, called, naturally, Base. Even this is useful by itself, if you just want to extract your artboard text for revision by wordsmiths, and then update it when they’re done, or even along the way in an iterative process.

But when you need multiple variants, you can open the Variants sub-panel to create, delete, and rename them. (See below)

Built-in help links

Note that each sub-panel, when expanded (“open”), shows a small circled-question mark to the right. Clicking on that icon will take you directly to the relevant portion of this user guide.

Artboards

The Artboards sub-panel is where you choose which artboards to work with, i.e., which artboards the operations in the D2D panel will affect. We call this the “scope” of D2D operations, or your “work area.” (D2D’s unit of operation is the artboard.) The scopes are:

  • All — D2D will work with all artboards (other than those marked ignored–see later);
  • Selected — D2D will work only with the current selection of artboards;
  • Marked — D2D will work only with the artboards you’ve “marked” as of interest.

[Note that Marked scope has nothing to do with the “Mark for export” control in XD. Also note you must select at least one artboard while working with D2D, no matter your scope, but only one (any one) to operate in general. That comes from a limitation of the way Adobe XD plugin interface is architected.]

This gives you a flexible set of scopes in which to work:

  • you can work with all (or most) artboards, marking a few “ignored” that will be entirely passed over for all operations;
  • you can work with a selection of artboards (again, ignoring those marked “ignored”);
  • you can “mark” a set of artboards to work with (which means they can’t be ignored), and then work with those.

You’re free to move among these scopes any time. The general idea is that, for a given design document, you’ll likely pick one scope and generally work in that. But you’re always free to change to any other scope at any time.

Marked / Ignored

(Before working with marking and ignoring artboards, you’ll first have to open the Artboards sub-panel by clicking on the “right-arrow” (closed) icon, which toggles to “down-arrow” (open), and then closed back again by clicking once more.)

If you want to designate a set of artboards as your working set, you “mark” them by selecting them in the Selected scope and then turning the Marked property on with the checkbox. Then, when you choose the Marked Artboards scope, you’ll be working exclusively with your chosen “marked” set.

Of course, you can always select and mark other boards (using the Selected scope), or unmark any board or boards in the marked set, to change what you’re working with. So, for example, you could mark a set to work with for a while, then change the marked set, and work with those for a while, etc.

You can also designate one or more selected artboards as “ignored,” which means that D2D will always pass over them in its operations.

You can also turn off all marked and ignored boards in the All scope by clicking on the respective checkbox, which will unmark or un-ignore all such marked or ignored boards.

Of course, if you unmark all artboards, then you can’t select the Marked scope until you once again mark one or more boards. And, if in Selected scope, if you have only ignored boards selected, you can’t really do anything with D2D. (The various D2D controls reflect these situations accurately to let you see what’s going on.)

Variants

The Variants sub-panel shows you which variant is currently applied to your current artboard scope in the menu (potentially multiple variants, listed below the menu in that case), and, simultaneously, the menu allows you to select which variant should be applied to the artboards in the current scope. And, the expanded sub-panel is where you manage your variants (and variant sets, which we’ll get to below).

Once created, you can “apply” a variant to your current set of working artboards by selecting that variant from the Variants menu, swapping in the selected variant’s content in place of the previously-selected variant’s content.

  • Initially, a variant won’t have any content peculiar to itself, so nothing will change when you first create it (which implicitly applies it to the working artboard scope). Only by editing or updating will a variant take on its own content.

  • A variant doesn’t have to have alternatives for everything in the base, but just those alternatives that make sense.

  • When a variant doesn’t have alternative content for a given text item (when the snapshot column for that variant is left (or made) empty on update), the base content is shown in its place.

  • If you edit a given text item when a given variant is selected, and the variant had no version of that text on its own, then that variant is given the newly-edited version.

  • If you edit a given variant’s text, leaving it the same as the base version, then the base version is once again “borrowed” and the variant text itself becomes empty.

  • When you’re editing a text artboard item in a non-base variant, the D2D panel warns you that you’re editing the variant, not the base. (Unless you edit it back to the base version’s content, in which case the variant version is once again empty and the base obtains.)

  • If you actually want a given variant to be empty, just change it to a single space. (Since you can’t have empty text objects in XD.)

This all sounds complex, but it’s designed to operate as naturally as possible. When you have a variant applied to a given artboard, if there is different content for that variant, it’s shown and is editable. If not, then the base variant text is shown, and that’s also editable. All with the obvious and natural results.

New

Choosing New in the Variants sub-panel creates a new variant (named Variant n, where n is the first number to make the variant name unique), and chooses that variant for (“applies the variant to”) the artboards in the current scope.

After creating a new variant, we recommend renaming it to something short and memorable, but of course you can leave it with the default name.

Delete

Choosing Delete for any (non-base) variant will remove all traces of that variant from the document, across all artboards, no matter what the current artboard scope might be. And the Base variant will be applied to all artboards where the now-deleted variant was once applied.

(This will require a modal confirmation in the future, since it’s fairly drastic.)

Rename

You can rename a (non-base) variant, when it’s selected for the current artboard scope, by editing the name field next to the Rename button, and choosing the latter.

You can’t rename to Base, obviously, nor can you rename something to any of the existing variants, nor can you include certain special characters in the variant name. The Rename button reflects all these rules, and is only enabled when the proposed name is valid.

Channel / Format

The Channel menu is shown first, and allows you to select a given channel (an input/output conduit). For now, there’s really only one choice, File, for file-based snapshots, but we expect to add others over time. (Google, in particular, is coming, for online access to Google Docs documents and spreadsheets, though we can’t predict when.)

The Format menu is shown second, and allows you to select a channel format. The most common are Sheet (Excel-format spreadsheet, working now) and Document (Word-format document, not implemented yet). (Those will also apply when Google Docs is supported.)

D2D currently also supports a JSON format for extraction/update in a machine-readable fashion, suitable for exchange with other software, and will support plain Text and CSV (delimited text) formats in the future.

(The Channel and Format sub-panels are shown as a single, merged sub-panel since they are so closely related.)

File

The File channel displays the name and read/write/read-only status of any open snapshot file, or just “No file is open.” When the sub-panel is expanded, more file information is displayed along with hints for various ways to open a file.

If an open file has been updated since it was last opened, the file status area will show that, and also warn about extracting to the open file while there are updates (which would be lost). Normally, you’d simply Update an updated snapshot file to pull in the changes.

A Close button is also enabled when a snapshot file is open.

Sheet

The Sheet format is expressed in a channel as a spreadsheet with one sheet per artboard, each named (as closely as possible) the same as the related artboard.

In each artboard’s sheet, there are columns for the text item index, the built-in Base variant, and then one column per variant. Each column is named by the corresponding variant.

Each text item has its own row, with one cell per variant.

You can edit any variant, including the base, but if you leave the base variant empty, then it will be unchanged on update.

The spreadsheet is “frozen” such that the variant header row, and the base variant columns are always shown, no matter how you scroll. This preserves your context when editing and lets you compare against the base no matter where you’re editing the sheet.

(There are also one hidden row and one hidden column that contain metadata which must not be edited; if you unhide them, they won’t do you any good and you can damage the snapshot and make it unusable.)

Extract / Update

The Extract / Update sub-panel houses the Extract and Update buttons and any options that are only shown when the sub-panel is expanded.

These buttons also reflect the scope of extraction and update; e.g., the extraction button becomes Extract All when the All scope is in effect, etc.

They also reflect (by appending a ) whether you’ll be prompted for an output file (for extraction) or input file (for update).

In any case, Extract (in its various forms) produces a snapshot of the current artboard scope. You must extract a snapshot before you can update from it, so Extract is first.

Update takes in a snapshot and updates the current artboard scope with it. Of course, there may be fewer artboards in the snapshot than in the current scope, in which only those artboards that are in the snapshot will be updated. And there may be other artboards in the snapshot not in the current scope, and those will not be updated. I.e., the scope and the snapshot are “intersected” to update just the ones in both scope and snapshot.

Further, with the Extract / Update sub-panel expanded, you can select which variants to update, defaulting to (All variants). If you select a variant other than (All variants) before updating, you’ll only update that selected variant. This can be quite useful when you want to focus on just one variant (e.g., one translation language), and not worry about all the others at a given point.

X-ray Vision

The X-ray Vision sub-panel is where you control the ways that in which D2D can give you deep insights into various aspects of variant content management which would otherwise be hidden behind the façade of normal-looking XD document.

For example, you can turn on artboard markers that show which artboards are marked and which are ignored.

And, you can turn on text item markers which, after an update or a variant switch, identify which text items were affected so you can review the changes.

This is critical information you need to help you understand “what happened” at each of these steps, so you don’t have to wonder what changed, and in what ways.

I.e., the controls here give you insight into each step along the way of D2D usage.

[This is all going to change fairly radically, so not documented here.]

Text

When you’re editing an artboard text item, D2D’s panel shows any relevant information about that item. For example, when editing when an artboard as a non-base variant applied, D2D warns you that you’re editing a variant.

[Need to flesh out both the functionality here and the documentation.]

Text Variants

When a single text item is selected, D2D displays the contents of any variants for the item. If the sub-panel is expanded, all the contents are shown, otherwise abbreviated versions are shown.

When a variant doesn’t have its own particular content assigned, it will show (see Base variant), since that’s what’s being used for that variant’s contents in the absence of any of its own.

XD Undo vs D2D operations

D2D tries to be robust in the face of undo’s of nearly any of its actions, but in general, try not to use undo after extractions / updates / variant switching, as that can confuse future operations. Rather, use the appropriate D2D action, like switching back to the previous variant.

Of course, if a particular update causes some serious problem, you can undo it, but just be sure to re-do any extraction before doing the next update.

(In particular, once an extraction is done, it reflects the state of the document at that point, and undo–ing afterwards means the extraction no longer reflects the document state. We try to guard against that as well, but we can’t always be successful.)

WordPress.org

© 2010 Em Software - Business WordPress Theme by ThemeShift