Creating documentation

[jm1]

I'm hoping to reorganize the documentation for our company's product. The documentation will have an public (for our customers) version and an private (for our support staff) version. The former version will describe the features of our software as will the latter, but the latter will also include technical information that we don't want/need to distribute to our customers. The private version will essentially be a superset of the public version. I need to be able to conditionally compile either of these two versions without checking a lot of boxes every time I need to generate a new version. I assume that I should be able to select documents for compilation based on, say, a label or status, but I can't find it in the documentation. Can someone point me to the right page?

I'm using the Windows version of Scrivener, if this matters.

Thanks in advance,
Jonathan

[brookter]

Yes you can do this, with a bit of preparation. The basic process could be:

1. Decide whether you want to use Labels, Statuses or Keywords. Any of the three will do: Labels have the advantage of allowing you an easy visual clue in the binder, so that's what I'll assume here, but see below*. Create the labels 'Public' and 'Private' and assign them to the relevant documents.

2. In the Project Search bar (the one on the top right next to the Inspector 'I' Icon), click on the magnifying glass and choose Label. While you're there, make sure the other options are make sense. Enter 'Public' into the search box and perform the search. The results will be shown in the binder. Once you're happy it's bringing up the right results, run the search again with the same criteria, but this time make sure the option 'Save Search as Collection' is checked. It will default to the word Public, but you can change that. You'll now have a Collection in the Binder -- and it's dynamic, so from now on when you add or remove the label Public to/from a document, it will automatically appear in / disappear from the Public Collection.

3. Do the same with the Private label and documents.

4. In the Compilation dialogue, make sure you're in the advanced section (click on the big down arrow), then choose Contents in the sidebar. There's a dropdown box above the list of documents -- click on it and you'll see your new Collections are available. Click on Public or Private as appropriate, make any other changes you want to the compilation options and then compile away...

Once you've got all the settings the way you want them, you can of course save compilation presets for Private and Public.

Of course there are lots of finer details you may need to address, but that's basically it. Hope it helps to get you started.



* The only issue with choosing a Label or Status instead of a Keyword is that you can only have one Label or Status per document, which means that if you've got front matter that is common to both public and private, you'll need to have two versions... So it would be easier to have Public and Private Keywords, and assign them both to common documents -- that way they'll appear in both Public and Private Collections.

[jm1]

Whoa! That's great.

Thank you again,
Jonathan

[AmberV]

One caveat to be aware of when using this method is that the compile list will be “flattened” to one level of hierarchy. The practical implication is that the amount of variation you will have available for formatting different types of sections will be limited to three in the Formatting pane (because everything is level 1). So long as you only need three “types” of documents in the sense of parts, chapters, section breaks or continuous text with no breaks, then you’ll do fine. Although files won’t be “in” folders in the compile list, the folder can still be set up to print a larger heading, break to a new page, etc.

Another approach is to use these collections as bit like a saved selection—that is once you click on the Collection tab in the main project window, you can view all of the items that have been selected by Private/Public, and press Ctrl-A to select the whole sidebar at once, viewing them as a multiple selection in the main editor. When viewed as an Outliner with the “Include in Compile” checkbox active, you now have a very easy way to bulk toggle all of the Private items off, then switch to the Public collection and do the same to toggle them on (or whatever you need). To switch all checkboxes in the outliner on or off at once, hold down the Alt key and click on any of the checkboxes.

This would be compatible with a “third” type of document, that is sections available to both Private and Public editions, if there is such a need. Those would simply not be defined in either collection, and thus never be toggled on or off by this procedure. While that method requires more manual labour from you, the advantage is that since you are using Include checkboxes, you get the full outline hierarchy at your disposal, which may be essential to you for documentation, where you’d need more than a couple of levels of subsection depth.

We’ll have some better stuff eventually for you, too, much better! The next major upgrade will several new features for building complex multiple documents out of one source, all the way down to the text level, not just per section with meta-data. Work with what you have for now though, these features are still very much in development.

[MrGruff]

I've used this method for maintaining two versions of a manual for thermal calculation software, one for the UK and one for Australia (each country uses different methods of calculating heat loss). I've not seen the flattening of the hierarchy in the collections, because I use MMD and produce the final manuals as PDFs through Latex.

I have three labels for documents: UK, OZ and Common, the last being documents which apply for both locations. Two very simple RegExs has allowed me to select UK + Common, or OZ + Common, to get the full manuals.

Code: Select all

(UK|Common)

and

Code: Select all

(OZ|Common)

Those are the only RegExs I know, but they work perfectly.