Writing developer's document and user's document

ruby-talk
1

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 : http://en.wikipedia.org/wiki/Software_documentation
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::
1. The best way to write : Latex or something else?
2. How to make it perfect-complete,impressive.
3. Any software which can help me with any part like UML?
4. Anything do I need to write for DRb?
5. 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.

···

--
Posted via http://www.ruby-forum.com/.

2

Developer docs are probably best written as rdoc inside the code. Check the standard library docs for array for a solid example.

User doc, what's your audience? Sys admins, end users etc. that informs the rest.

The software you use to put it together doesn't really matter as long as it is well written.

···

On 3 Oct 2012, at 12:10, ajay paswan <lists@ruby-forum.com> wrote:

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 : http://en.wikipedia.org/wiki/Software_documentation
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::
1. The best way to write : Latex or something else?
2. How to make it perfect-complete,impressive.
3. Any software which can help me with any part like UML?
4. Anything do I need to write for DRb?
5. 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.

--
Posted via http://www.ruby-forum.com/.

3

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).

···

Am 03.10.2012 20:10, schrieb ajay paswan:

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 : http://en.wikipedia.org/wiki/Software_documentation
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::
1. The best way to write : Latex or something else?
2. How to make it perfect-complete,impressive.
3. Any software which can help me with any part like UML?
4. Anything do I need to write for DRb?
5. 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.

--
<https://github.com/stomar/>

4

Jam Bees wrote in post #1078558:

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'.

Anything like Rdoc for writing user_doc?

···

--
Posted via http://www.ruby-forum.com/.

5

How these: http://rubydoc.info/gems/document/1.0.1/frames documents are
done?

···

--
Posted via http://www.ruby-forum.com/.

6

Jam Bees wrote in post #1078558:

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.

Anything like Rdoc for writing user_doc?

I don't know.

···

On 4 Oct 2012, at 02:06, ajay paswan <lists@ruby-forum.com> wrote:

7

How these: http://rubydoc.info/gems/document/1.0.1/frames documents are
done?

Generated from rdoc, normally. Seriously, check the ruby implementation of some stuff in the standard library, you'll see.

···

On 5 Oct 2012, at 00:05, ajay paswan <lists@ruby-forum.com> wrote:

--
Posted via http://www.ruby-forum.com/.

8

> Jam Bees wrote in post #1078558:
>>
>> 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.

···

On Thu, Oct 04, 2012 at 11:12:03PM +0900, Jam Bees wrote:

On 4 Oct 2012, at 02:06, ajay paswan <lists@ruby-forum.com> wrote:

--
Chad Perrin [ original content licensed OWL: http://owl.apotheon.org ]

9

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:

RDoc::Markup <http://rdoc.rubyforge.org/RDoc/Markup.html>

Hope that helps,

···

2012/10/5 Jam Bees <jam@jamandbees.net>

On 5 Oct 2012, at 00:05, ajay paswan <lists@ruby-forum.com> wrote:

> How these: http://rubydoc.info/gems/document/1.0.1/frames documents are
> done?
>

Generated from rdoc, normally. Seriously, check the ruby implementation of
some stuff in the standard library, you'll see.

> --
> Posted via http://www.ruby-forum.com/.
>

--
Carlos Agarie
Control engineering student
Polytechnic School
University of São Paulo