Project Documentation in Scrivener

I manage a number of web and application development projects and am always looking for a better way to write, manage, and maintain documentation.

Does anyone have any thoughts on the suitability of Scrivener for this sort of thing? I do like the idea of keeping a collection of documents together in a Scrivener project, then being able to create final documentation in a number of formats.

Things like…

  • Release notes
  • Design decisions
  • Hardware/Software configuration
  • Setup and configuration procedures
  • Workflow notes
  • etc.

Scrivener, the few times I’ve tinkered with it, has always felt like a great solution to a problem I may not even have. Maybe project documentation could be that problem :slight_smile:

Jack

I’m increasingly edging towards this style of working - and more compellingly so now that I can set up proformas (document level templates).

I currently have a general dumpbin project of notes, config files and user manuals (some written by me and some by others). It’s a bit cluttered, now that we have collections as another way of organising, I will probably start using keywords more to help organise this into stages, or work bundles.

I guess eventually I’ll end up with a ‘Project’ project template, that includes standard docs for my methodology, with folders for doc templates, end user manual/training guide, issues lists etc (I guess you could run each issue as a scrivening). I don’t think Scriv can do symlinks - if it could, then I’d just live in there.

At the very least I will continue to maintain my ‘This is how I do X’ technical notes in Scrivener.

A custom project template seems like a great idea. I’m not familiar with Scrivener templates yet, but will investigate.

Right now I’m struggling with what to keep “loose” in my massive DEVONthink projects database and what I should keep in something like Scrivener. The idea right now is to use Scrivener as a place to write and keep only “final” documentation for each area, and continue to keep most reference material and other loose notes in DEVONthink.

It’s not quite project documentation, but I have just written my first client manual in Scriv. As it’s essentially the same manual from client to client, but with one or two pages different I have set it up as follows:

I have two Labels: Generic, and Client Specific (as aide memoires)
I have created keywords for all my clients.
I add all clients to the scrivenings labelled Generic, and create client-specific pages with client-specific keywords.
I then run a search for the client as a keyword, and save that search as a collection.
I then compile that collection.

And voila - I have a sausage machine.

ie
Front page

  • Client A manual front sheet (clientA)
  • Client B manual front sheet (clientB)
    Section 1
  • Widget making (clientB, clientA)
  • Special widget making (clientA)
  • Grommit building (clientB,clientA)
    Section 2
  • Tips and tricks (clientB, clientA)
  • Dummies guide (clientB)
    Section 3
  • References (clientB,clientA)

Compile for Collection of ‘keyword=clientA’

Of course I could simply duplicate projects for each client, but this means that there would be discrepancies between manuals. This way, an update for one is an update for all.

I guess I could take this further and add client-specific screenshots on different scrivenings. So far I’ve been working to the assumption that I would overwrite these depending on how tied-in to a client they were.

That’s the beauty of having a system that treats a unit as either the Enyclopedia Britannica or a single word, depending on your mood. As it compiles ‘inline’ Scriv would simply put the image (more or less) where I wanted it.

PS I was also extremely lazy and compiled an Outline Enumerated PDF, and then copied that back into my front sheet as a pseudo TOC, because I didn’t want to either manually create one or do anything in Word/NeoOffice. Huzzah!

Have you had a chance to check out Scrivener’s ToC feature yet? Check out the PDF under Part 3: Final Phases. There is a small chapter on how to use this feature and what it does (and doesn’t do) precisely. For word processors (those that support RTF bookmarks and cross-refs), it will generate a simple static ToC. It also works in PDF/Print mode.