Fog Creek Software
Discussion Board




Second try: designing a documentation system

Since my previous flood of words was overwhelming to most, I'm retrying, with less words and more concepts

Well, the idea is to (loosely) mirror a filesystem. A filesystem may look hierarchical, but, actually, it has a flat, integer-indexed table of all files, and some files (directories) are special in that they contain other files

In my case, there's many flat, string-indexed tables of topics, and some topics ("section", "reference", etc.) are special in that they contain other topics

Since others have asked about requirements, here they are:
- structural fluidity. All topics, except reference pages, could grow, and need to be moved to an upper level, or into their own section. An example is the documentation for the ReactOS user interface: initially it could start as a subsection of the ROS32 platform documentation, but since there's more to a GUI than just CreateWindow, it will need to be moved out, into a dedicated User Interface Development section, containing, for example, subsections about accessibility, internationalization, etc. This, of course, must not invalidate any internal URL, nor require a full recompilaton
- storage staticity. Documentation files, in their source code form, must not be renamed nor moved, because CVS doesn't support it
- flat indexing. Have you ever used the "man" Unix command? The idea is that. If you only need a quick reference, you shouldn't be forced to precompile and/or keep a X MB index file - the filesystem is enough
- support for a hierarchical view. This is going to be hard. I'd gladly use subdirectories, rather than inventing my own format for definition of section hierarchies (or try to adapt to DocBook's), but the previous requirements leave me no choice

What worries me the most is the hideous proliferation of small XML files in a few flat directories that this will cause. This could be mitigated with some sort of internally used, fixed hierarchy - i.e. the key of "ReactOS User Interface" in the "section" index will become, from "gui", something like "winbase/gui"

KJK::Hyperion
Monday, December 16, 2002

Good god, *I* have to provide a serious response.

Anyway, the key is to separate the structure entirely from documentation (something that Xmetal is good at, although it's a horrible documentation tool.)  Put all your layout in some sort of XML-style hierarchy in a single file, and rearranging becomes no big deal.

http://www.softquad.com/top_frame.sq?page=products/xmetal/content_xmetal_intro.html

Jason McCullough
Monday, December 16, 2002

No, really, what's the matter? will someone please give me a clear answer? is this some kind of collective prank you're pulling on me? I don't get it, honest

I've written my post in English, right? it's not my native language, but I think I can speak it quite good, can't I? This is a forum about software engineering, right? not Utzbek fine cuisine, software engineering... right? People post messages here to get, you know, comments, right? I'm not getting any of this wrong, right?

I don't know, does the fact that there's no money, deadlines, management, etc. involved confuse you or something? does the fact that I don't explicitely say "if someone has had previous experiences with a similar problem, please let me know if you think it's going to work or if you can spot glaring design holes from a mile" make you _really_ think that I'm posting these messages just for the heck of it? or what?

Is lack of experience a crime? is being born too late to follow the evolution of more than two consecutive releases of the Microsoft PSDK a crime? is not knowing if I'll actually need as much topic-reshuffling as I prepared myself to a crime? is asking more experienced people if I'm overengineering a crime? is ASKING a crime?

Enough questions for you? geez

KJK::Hyperion
Monday, December 16, 2002

> Anyway, the key is to separate the structure entirely
> from documentation (something that Xmetal is good at,
> although it's a horrible documentation tool.) Put all your
> layout in some sort of XML-style hierarchy in a single file,
> and rearranging becomes no big deal.

<shame>I've read some more about DocBook, and it looks like I was just trying to reinvent it, after all</shame>

Initially, I thought that the XML hierarchy would be unfeasible, because a single, monolithic file would be a hell to manage. Especially because many subsections could become full guides of their own, and be distributed separatedly - each with its own index??? This was enough to keep me away from the "unified XML index"

Then (about a minute ago) I discovered I can include subdocuments in an XML document by defining some XML entities and putting them in place of the full document:

<?xml version="1.0"?>
<!DOCTYPE book SYSTEM "doh/docbookx.dtd" [
<!ENTITY blah SYSTEM "blah.xml">
]>
<set>
<!-- inserts blah.xml here -->
&blah;
</set>

what can I say? sorry for the noise. Had I kept reading the DocBook manual just a hour longer, none of this would have been necessary

KJK::Hyperion
Monday, December 16, 2002

really, i'm not kidding. the problem is that your post doesn't contain a question! 


Monday, December 16, 2002

> really, i'm not kidding. the problem is that your post doesn't
> contain a question!

it was a follow-up to a previous post of mine (I don't recommend reading it, though - unless you suffer from insomnia). The question was there

Sorry for freaking out, but when people keeps giving you funny looks instead of answers, you start to suspect that maybe, when you open your mouth, a musical box sound comes out instead of your voice. But you don't realize it and <dling><dling><dlong><dling><dliiing>

KJK::Hyperion
Monday, December 16, 2002

Would you conclude that the world is against you or something ? It's called paranoia ya know ?
Relax.

Not wanting to receive spam
Tuesday, December 17, 2002

KJK - I quickly read through both of the threads you started and found it very hard to follow what you were saying. I don't really understand what your project is, except that it's a "documentation system" and it somehow involves a Win32 interface.

There's nothing wrong with asking a group of peers for advice, but you're most likely to get advice if you make it easy for people to give you advice. That means being clear and concise and giving enough high-level background info. I'm reading the message boards over coffee before a meeting, so I don't have time to look at your project's web site or an in-depth example and I'd guess that most other readers here don't either.

A more effective approach might have been to start with a paragraph that explained what the overall project is. Follow that with a brief description of the specific problem on which you'd like input, and then phrase your question clearly at the end.

The advantages of the approach I'm suggesting are that it'll be easy for readers to follow and you're more likely to get specific suggestions about the problem you're trying to solve (instead of more general suggestions like "why not write it in Lisp?"). Also, I find that when I take the time to write things out clearly for someone else, I often stumble on the right answer before I finish the writing and then I don't need to ask at all.

Beth Linker
Tuesday, December 17, 2002

Hi Hyperion,

instead of dumping a whole lot of information on us and ask a very unspecific "So what do you think?", it would be better to think about your approach and ask littly tiny questions about the parts of it that you are not yet comfortable with. Then the answers will be more specific, too, I guess.

If you are still uncomfortable with too many parts of your design or feel very unsecure about where to begin, you should probably go through all of it with someone point for point, but you would better do this with one person at a time, preferably someone from your direct working environment, so you can sit together and talk. (It is a whole lot easier to communicat that way than via email). A forum like this just is not the right place for that kind of work.

Have fun,

Jutta Jordans
Tuesday, December 17, 2002

> Would you conclude that the world is against you or
> something ?

no, no, I'm just acknowledging a series of coincidences. A long series of coincidences. A suspiciously long series of odd coincidences... hey! did you hear that?

KJK::Hyperion
Tuesday, December 17, 2002

> KJK - I quickly read through both of the threads you
> started and found it very hard to follow what you were
> saying. I don't really understand what your project is,
> except that it's a "documentation system" and it
> somehow involves a Win32 interface.

when I say "just like MSDN", I mean it. ReactOS is a project for the development of an open source clone of Windows, everything included - kernel, standard drivers, libraries, system programs, etc. *and* the huge MSDN library. I explained it in a previous post (but then, again, this isn't Usenet)

And I'm the librarian - for lack of other candidates, to be honest - of said project, so I handle everything documentation

Anyway. This whole question can be summed up with:
- RTFM - had I read the DocBook manual more in depth, I wouldn't have even needed to ask, nor come out with that byzantine design
- The Fog Creek Forum Is Not Usenet

KJK::Hyperion
Tuesday, December 17, 2002

*  Recent Topics

*  Fog Creek Home