Best way to document?
SirG3
lib, preferences lib, and a few small things), and I was wondering
what the best way to document this stuff is. I really, really hate
documenting things ><.
-- SirG3
Ed Kleban
There is a very good argument for the tool you have and know well, rather
than learning a new tool for the job. Especially if you hate documenting
things. That said, depends on how you want to present the documentation.
Some options include:
If it's just a doc you want people to be able to download as a PDF, text, or
.Doc file, then write it in MS Word if you have it or Mac TextEdit or
Windows WordPro if you don't. There are free alternatives on both Mac and
Win platforms for subsequently generating a PDF file, or if you save a
".rtf" file from any of these three editors than anyone should be able to
open it on pretty much any machine. ".rtf" is fine for doc of a few pages.
If your serious about making and maintaining some quality documentation, you
may well want to consider using MS Word.
You can then presumably publish such controlled docs in a REALOPEN project.
If you want to publish the documentation in a format that it can be
integrated as Help text inside of an application. Or if you want to
generate help files as well as web pages and PDF manuals, it's well worth
looking at:
http://www.ebutterfly.com/helplogic/
http://www.ebutterfly.com/helplogic/guide/index36.html
If you want to publish documentation that others can view, correct, and keep
up to date for you, you can certainly add it to:
And there's no reason you can take advantage of all of the above. They all
have their uses.
Keith Hutchison
> If you want to publish the documentation in a format that it can be
> integrated as Help text inside of an application. Or if you want to
> generate help files as well as web pages and PDF manuals, it's well worth
> looking at:
>
> http://www.ebutterfly.com/helplogic/
> http://www.ebutterfly.com/helplogic/guide/index36.html
I found help logic to be great for user documentation.
For system docu I'd look at posiedon or visual-paradigm, both of which
produce uml documentation. Posiedon has a free community uml version
http://www.gentleware.com/
I prefer the interface for visual-paradigm. http://www.visual-paradigm.com/
I use both.
--
Keith Hutchison
http://balance-infosystems.com http://realopen.org
Timo Ruohomäki
and how much can one assume that users need to modify it.
One very handy feature (or plugin) for RB would be an export tool that
would help documentation a lot. Basically technical documentation is a
list of modules and classes and their methods and properties. If all
that could be exported from IDE into a simple table it wouldn't be a
big effort to fill in the explanations for all those.
So, if any of you have any spare time there's a little task... :)
//timo
Keith Hutchison
>
> Naturally the requirements depend on the module, e.g. how 'ready' is it
> and how much can one assume that users need to modify it.
>
> One very handy feature (or plugin) for RB would be an export tool that
> would help documentation a lot. Basically technical documentation is a
> list of modules and classes and their methods and properties. If all
> that could be exported from IDE into a simple table it wouldn't be a
> big effort to fill in the explanations for all those.
Have a look at http://rbwiki.org/doku.php/rbp/rb.analysis.tools
Thomas Tempelmann's RB Project Tool is most of the way there.
Keith
Ed Kleban
On 12/20/05 4:16 PM, "Keith Hutchison" <keith.kjtl...@gmail.com>
wrote:
Yes. We've been discussing plans to:
1) Expand RBProject Tool to support export to Doxygen for just such a
purpose.
2) Expand RBProject Tool to include a capability similar to that of JavaDoc
either as an independent documentation facility or perhaps as a preprocessor
that indeed feeds it's output straight into JavaDoc.
3) Establish a "REALdoc" standard set of "@Tags" similar to those of JavaDoc
so that developers can flag in comments which aspects of their code they
would like to include in the documentation for purpose of Javadoc style
filters. We've also proposed using such standard tags for offering clues to
source analysis software such as Reality Check.
If you are interested in contributing ideas to projects such as these, or
monitoring the development process of those who are, or even just stand
around on the sidelines and take potshots while laughing at us, feel free to
join the REALsource discussion group:
* Group name: REALsource
* Group home page: http://groups.google.com/group/REALsource
* Group email address: REALs...@googlegroups.com
* Group description on RBWiki: http://rbwiki.org/doku.php/rbp/realsource
Summary:
³REALsource² is the name of a RB-community project to develop and promote a
common, reusable toolbase for the reading, parsing, comparing, modifying,
analyzing, and editing of REALbasic source code through the use of new
applications written in REALbasic.
Riaan Pretorius
Thanks