|
Documentation for software product
Basic advices How to write the documentation for software product.
Document: External specification
(RUS) Contents of external specification
Document: whatsnew
If your program is equipped with whatsnew then
- users see that you are working hard and support your activity,
- they are waiting for special fixes and announcements,
- they get news about new features of your program.
How to update whatsnew?
- You have todo list. Move executed tasks from todo list to whatsnew file.
- Don't write long paragraphs of text, 1 line - for 1 big-fix
Document: known issues
Если программа большая, чтобы избежать проблем, публикуйте
Known-issues (Release notes)
Какие ограничения у текущей версии?
если мы предупреждаем, что виснет в случаях: a), b), то все ОК.
если юзер сам нарывается на вис - вот где он звереет.
Document: .HLP/.INF files
It's possible to write simple IPF code directly with an text editor.
For more complex and highly-linked documents, that would be a very
uncomfortable option.
Examples: there are many .ipf in toolkit -> samples
x:\PROG\Toolkit45\SAMPLES\PM\IPF
There exist a couple of suitable IPF preprocessors:
- Html2Ipf uses HTML as its source file format. As its biggest
advantage, any HTML editor can be used, even a WYSIWYG one. It
does a good job, but also has disadvantages: You'll have to
maintain countless HTML files (one file per IPF page). Moreover,
there exist some minor issues with vertical spacing.
- Vyperhelp has a GUI, but unfortunately produces poor output.
Lists are not handled correctly in the IPF files. That will
lead to hardly portable help file sources.
- Hypermake is in some cases more powerful than HyperText/2, but
costs a shareware fee. Additionally, its IPF output has a few
spacing issues.
- HyperText/2 doesn't come with those drawbacks, but you have to
"learn" another new language. That language is simple, but you
have to read at least a few pages of this doc (or look at the
examples) before being able to use it. Its input source files
are highly readable, especially with an text editor supporting
syntax highlighting for HyperText/2. So WYSIWYG editing is not
required. Moreover, the Ipf2Htext compiler allows for using
source files, that were originally not written with HyperText/2
and exist only in the IPF format. Compared to other IPF import
solutions, manual postprocessing is not required in most cases.
|
