
Show HN: Doc42 – Simple documentation tool - afshinmeh
http://doc42.io/
======
dozzie
When are you going to document this _documentation tool_? It's the third time
I see this on HN and I still can't tell how to use it or what to compare it to
(what it is supposed to replace).

~~~
afshinmeh
this is my comment on the other thread:

> ah sorry I missed this one. can you please let me know what do I need to
> add? I thought I have covered almost all topics and parts in order to be
> able to build a documentation. In other words, what you expect to see there?

~~~
dozzie
Yeah, the other thread, from week ago, and comment from two hours ago. I had
the time to already forget about your project and drown my comment about it
with other comments before you replied there.

As I said here already, I can't tell how to use it and what to use it for.

Let's assume I have a project that already has some code and no documentation.

First thing I want to know is what kind of artifacts your thing produces. This
is important and there are several valid options, which include "HTML pages to
publish on a generic web page", "HTML to be published on readthedocs", and
"man pages".

Then I want to know how to start actually using the tool. Remember: I don't
have any documentation structure and I know nothing about your tool. I don't
know if it uses documenting comments (JavaDoc/Doxygen style), separate text
files (SGML/asciidoc style), or maybe a combination of these (like Sphinx
does). I don't know how to run your tool to generate the thing and how to
control its output.

Then there is the issue of semantic markup. Any sensible documentation tool
allows the writer to distinguish several important types of things, like
functions, classes, and modules, and it does so in a single, designated way
that results in always looking the same. I haven't seen anything like that in
your tool, which means I, as an author, need to constantly remember how I mark
the functions and modules.

You should compare how your documentation looks standing beside Doxygen,
Sphinx, or much simpler asciidoc and POD (Perl's plain old documentation).

