The best format for any documentation depends not only on the information it carries but also on the intended audience. If your audience consists of software engineers, I would say UML is a good choice: it is standardized, which means you won't have to make up your own notation or explain it, and if you keep the diagrams reasonably simple the odds are good that your audience will be able to read them even if they aren't full-on UML experts.
You don't say what the documentation is for, but at a minimum I would suggest the following sections in your report:
Source View: class diagrams, possibly with a few package diagrams as well depending on the implementation language and the number and type of packages. (If the packages provide functional abstractions, like they can do in Java, consider describing them; otherwise it's not hugely important.)
Runtime View: sequence diagrams describing the flow of control for at least the key functions.
You may also consider adding one or more of these:
Overall Design: a component diagram describing the main parts of the software: for instance a DLL and an API being called by the user's code (I assume we're talking about some sort of library routine). This should not be concerned with specific method calls or implementation classes, but describe the software at a high level.
Conceptual View: this should describe key concepts, typically using very simple class diagrams. File is probably one such, and you should consider including a state chart describing the different states of a file (open, closed, eof...).
As always when using UML to document (rather than for instance generate code), be generous with notes in each diagram, and sparse with elements (classes etc). For diagrams intended for pasting into text documents, I try not to put more than a half dozen elements in each diagram.
发布评论
评论（2）
使用 UML 活动图 (http://www.agilemodeling.com/style/activityDiagram.htm) 来了解高层流程。
然后，使用 UML 序列图 (http://www.agilemodeling.com/artifacts/sequenceDiagram.htm) 来表示足够复杂的部分以保证进一步的细节。
Use UML Activity Diagram (http://www.agilemodeling.com/style/activityDiagram.htm) for the flow of the processes at a high level.
Then, use UML sequence diagram (http://www.agilemodeling.com/artifacts/sequenceDiagram.htm) for portions complex enough to warrant further detail.
任何文档的最佳格式不仅取决于它所包含的信息，还取决于目标受众。如果您的受众是软件工程师，我会说 UML 是一个不错的选择：它是标准化的，这意味着您不必编写自己的符号或解释它，并且如果您使图表保持相当简单，那么可能性就很大即使您的受众不是全面的 UML 专家，他们也能够阅读它们。
您没有说明文档的用途，但至少我会建议您的报告中包含以下部分：
源代码视图：类图，可能还有一些包图，具体取决于实现语言以及实现的数量和类型包。 （如果包提供功能抽象，就像它们在 Java 中所做的那样，请考虑描述它们；否则它并不是非常重要。）
运行时视图：至少描述关键功能的控制流的序列图。
您还可以考虑添加以下一项或多项：
总体设计：描述软件主要部分的组件图：例如用户代码调用的 DLL 和 API（我假设我们正在讨论某种库）常规）。这不应该关心具体的方法调用或实现类，而是在高层描述软件。
概念视图：这应该描述关键概念，通常使用非常简单的类图。文件可能就是这样的，您应该考虑包含一个描述文件不同状态的状态图（打开、关闭、eof...）。
与往常一样，当使用 UML 来记录（而不是生成代码）时，请在每个图中慷慨地添加注释，并稀疏地使用元素（类等）。对于要粘贴到文本文档中的图表，我尽量不要在每个图表中放置超过六个元素。
The best format for any documentation depends not only on the information it carries but also on the intended audience. If your audience consists of software engineers, I would say UML is a good choice: it is standardized, which means you won't have to make up your own notation or explain it, and if you keep the diagrams reasonably simple the odds are good that your audience will be able to read them even if they aren't full-on UML experts.
You don't say what the documentation is for, but at a minimum I would suggest the following sections in your report:
Source View: class diagrams, possibly with a few package diagrams as well depending on the implementation language and the number and type of packages. (If the packages provide functional abstractions, like they can do in Java, consider describing them; otherwise it's not hugely important.)
Runtime View: sequence diagrams describing the flow of control for at least the key functions.
You may also consider adding one or more of these:
Overall Design: a component diagram describing the main parts of the software: for instance a DLL and an API being called by the user's code (I assume we're talking about some sort of library routine). This should not be concerned with specific method calls or implementation classes, but describe the software at a high level.
Conceptual View: this should describe key concepts, typically using very simple class diagrams. File is probably one such, and you should consider including a state chart describing the different states of a file (open, closed, eof...).
As always when using UML to document (rather than for instance generate code), be generous with notes in each diagram, and sparse with elements (classes etc). For diagrams intended for pasting into text documents, I try not to put more than a half dozen elements in each diagram.