Ok, I am writing an implementation guide for my project, x86Lib. This is the first time I've ever wrote any technical document like this, and I'd just like to know how I am doing so far...
I have a feeling that I don't explain enough, but it seems obvious to me...
Also, I write the document in .odt (openoffice 2.0) form, and then export it to PDF... I would like it to be in html, but the html writer makes it not look very good, so anyone know of a good web-viewable format other than PDF?
http://earlz.biz.tm/x86lib_guide.zip
Also, I just realized not everyone is using windows, so if you are not using windows, you'd have to make x86lib to see the samples...
Can you understand this?
-
GuiltySpark
- Posts: 7
- Joined: Sun Dec 16, 2007 9:47 am
- Location: The (Other) Counterweight Continent
I recently had experience writing technical documentation. The basic principle I find helpful is to leave detailed description of the code to the code comments. As for the actual document itself, I followed this format:
1) List the common uses of the code. By that, I mean the high level goals/use cases your library is providing.
2) Then list the common steps needed to achieve the goals and the general (no code) set of modules and their relationships (no code yet).
3) Then for each goal/use case, list every step. Even the common, repetitive ones. It's tedious, but scrolling up and down (or switching between pages) is not helpful at all. In general, the principles of modularity and divide/conquer is not good for technical documentation.
4) Then for each step, write the code.
5) Very important: include references (pseudo-Harvard/Chicago) even if it's your own code/information.
As for writing style (which is just as important as technical content):
1) Do not break the 4th wall. It breaks the flow, interrupting the reader's thinking. By 4th wall, I specifically mean making references to, eg, that your documentation is may be lacking in detail because you were the writer. It's good and well to be honest about it, but it's probably best to leave that to the introduction of the tutorial/guide.
2) Try not to have a conversation with the reader. ie, try writing like a lecturer, not a tutor. This is my personal preference, though. ie, I find it easier to read if it doesn't read like the writer is trying to talk to me.
3) I haven't read much cookbooks or recipes but I think they could be good examples.
4) No exclamation marks. If a sentence feels like it needs one, rewrite the sentence to be less "emotional".
HTML should be fine. A project I worked on used DOxygen to generate code docs as well as tutorials/guides.
1) List the common uses of the code. By that, I mean the high level goals/use cases your library is providing.
2) Then list the common steps needed to achieve the goals and the general (no code) set of modules and their relationships (no code yet).
3) Then for each goal/use case, list every step. Even the common, repetitive ones. It's tedious, but scrolling up and down (or switching between pages) is not helpful at all. In general, the principles of modularity and divide/conquer is not good for technical documentation.
4) Then for each step, write the code.
5) Very important: include references (pseudo-Harvard/Chicago) even if it's your own code/information.
As for writing style (which is just as important as technical content):
1) Do not break the 4th wall. It breaks the flow, interrupting the reader's thinking. By 4th wall, I specifically mean making references to, eg, that your documentation is may be lacking in detail because you were the writer. It's good and well to be honest about it, but it's probably best to leave that to the introduction of the tutorial/guide.
2) Try not to have a conversation with the reader. ie, try writing like a lecturer, not a tutor. This is my personal preference, though. ie, I find it easier to read if it doesn't read like the writer is trying to talk to me.
3) I haven't read much cookbooks or recipes but I think they could be good examples.
4) No exclamation marks. If a sentence feels like it needs one, rewrite the sentence to be less "emotional".
HTML should be fine. A project I worked on used DOxygen to generate code docs as well as tutorials/guides.
"Pissing people off since 1986."
"Edible: n, As in a worm to a toad, a toad to a snake, a snake to a pig, a pig to a man, and a man to a worm."
"Edible: n, As in a worm to a toad, a toad to a snake, a snake to a pig, a pig to a man, and a man to a worm."
Re: Can you understand this?
http://pdftohtml.sourceforge.net/hckr83 wrote: Also, I write the document in .odt (openoffice 2.0) form, and then export it to PDF... I would like it to be in html, but the html writer makes it not look very good, so anyone know of a good web-viewable format other than PDF?
HTH