![[personal profile]](https://www.dreamwidth.org/img/silk/identity/user.png){kind=small}
documentation toolkit
Our company makes an SDK (software development kit). That means that we sell our product to people who then use it to make their own products. We provide documentation for those programmers. We also provide the building blocks of a user interface, which they can use or not.
It was only a matter of time before we had to start worrying about user documentation for that interface. Now, we can't just do up a user guide for the interface, because our customers can modify it and need to be able to produce their own customized user guides to go with. And we can't, it turns out, just make them do all their own user documentation. (We currently provide a quick-start guide, a UI cheat sheet of sorts.)
So I'm now thinking in terms of a "UDK", a "user doc kit". Like the SDK, we would supply building blocks and they would put them together as best suits their needs. As with the SDK, we would provide a basic implementation that makes sense and that they can use if they like.
I know I'm not breaking new ground here, but I'm enjoying thinking about the parameters of the problem so I can structure it appropriately. (It even makes up for the prospect of having to write some of that user doc...) We need to support people using everything from HTML to Word to Frame to some Mac-specific PageMaker-like tool (I don't know its name), so it looks like I'm going to settle on unformatted text files and standard graphics formats (JPG, PNG, etc) as the portable common format. I'd like to do something a little richer than that; we'll see. (I proposed XML or HTML but they didn't like that.)
We have a project in-house that needs user documentation, so I'll have a handy guinea pig. They asked me for help with user docs; I sold them this approach instead, which is generalizable. It would be stupid to just do a project-specific user guide and later raid it, cut-and-paste style, for the next project that needs this. Besides, this way we can package the bits for customers, too.
no subject
Actually, in this particular case I'd say that flat text is probably a good idea. There are so many different presentation formats that folks could use (including flat text) that even HTML isn't necessarily importable everywhere. And doing it with flat text pretty much assures that the actual doc writers won't get lazy with the formatting. (Which would probably go badly.)
I'd think of it as a content vs. presentation issue. You're trying to provide a toolkit of content, but you should be shying as far away from the presentation end as you can. Even if you were going to use HTML, I'd probably recommend sticking only to the most trivial tags, so it wouldn't be much more useful than plaintext anyway.
That said -- very neat idea. I actually haven't come across this concept in any of the SDKs I've worked with or on, and it strikes me as both clever and useful for certain kinds of kits (particularly OEM/VAR oriented ones)...
no subject
Hmm. I wonder if I could use XML and also ship a processor that would simply strip out all markup -- so if you want plain text it's there, but if you want the semantics you have them. I've never actually written a DTD, though, and I'm not likely to get help on this. I suppose there's always regexp-replace -- I could use XML and then ship text, and when people complain that they can't figure out the section breaks I can hand over my original XML instead. That could work.
I actually haven't come across this concept in any of the SDKs I've worked with or on
Wow. It seems like an obvious need (in some products) to me, but I'll admit that this is the first SDK I've worked on where we're actually going to do it. I haven't much been on the receiving end, so I haven't noticed the general absence of this.