I have developed a software using DRb, now as I have completed I want to
write a nice complete and impressive developer document and user
document.
I have just started with Latex and IPE. Is there any other software to
write it?
Am following : Software documentation - Wikipedia
I am writing extensively using UML.
Am I missing something? how to make it effective and COMPLETE?
Is there any readymade tool like in IntelliJ IDEA which I should be
using? Anything is there like this in rubymines? I have both IDEA and
rubymines.
So the simple question are::
The best way to write : Latex or something else?
How to make it perfect-complete,impressive.
Any software which can help me with any part like UML?
Anything do I need to write for DRb?
Diffrence between developer’s doc and user’s doc? What they include?
Please give me some pointer to get me going in the best way to write
doc.
Developer docs are probably best written as rdoc inside the code. Check
the standard library docs for array for a solid example.
Do I need anything apart from RDoc?
User doc, what’s your audience? Sys admins, end users etc. that informs
the rest.
Audience is end users, say layman.
The software you use to put it together doesn’t really matter as long as
it is well written.
What does it mean by ‘well written’.
Developer docs are probably best written as rdoc inside the code. Check
the standard library docs for array for a solid example.
Do I need anything apart from RDoc?
Only if you want something different.
The software you use to put it together doesn’t really matter as long as
it is well written.
What does it mean by ‘well written’.
I imagine this is a translation problem. Well written for me means that
there are examples of usage etc.
Well written means the documentation is informative and tells you how to
actually use the software.
Developer docs are probably best written as rdoc inside the code. Check
the standard library docs for array for a solid example.
Do I need anything apart from RDoc?
Only if you want something different.
Learning the basics of creating gems is a good idea when creating Ruby
applications, in part because in combination with RDoc your gem
specification+rakefile provides the necessary configuration to have the
Ruby gems toolset to automatically set up RDoc for access by way of both
command line ri and local browser interface.
Anything like Rdoc for writing user_doc?
I don’t know.
At minimum, I tend to provide --help output using OptParse, with
extensive syntax and usage documentation. Depending on the specific
application, a manpage might be a good idea; there are some Ruby gems
that are helpful for generating manpages (and other documentation
formats) from simple text formats (including RDoc). If you want some
kind of user documentation embedded within a captive interface
application, you might have to roll your own help documentation tools,
depending on your specific desires.
using? Anything is there like this in rubymines? I have both IDEA and
For user documentation which is not directly linked to the source code
you might consider using markdown. I use pandoc to convert the matkdown
to HTML and PDF. pandoc extends the “pure” markdown syntax a bit,
supports syntax highlighting for Ruby, and can convert to many output
formats (including LaTeX).
Actually, there were created using YARD http://yardoc.org/, which is a
bit more complex and powerful. You can read more about rdoc in the
documentation http://rdoc.sourceforge.net/. This is the link for the
markup documentation specifically: