Documentation

[james-prior]

We will have succeeded when a non-technical person that we do not know is able
to successfully use one of our arduino based things, just by following our
instructions on github, without any coaching or hand-holding by us.

We need instructions to install, compile, download, and run the Arduino
software. That would include:

• requirements
  • hardware
    • development host
    • arduino
      • say which boards are supported
        • be specific
      • what other hardware is required
        • power supply
        • cables
      • what hardware configuration is required
        • for example, cables or I/O modules
  • software
    • development host (computer that runs Arduino IDE)
      • how to download and install development system
        (ok to refer to specific Arduino URL for this)
      • how to install git
      • how to install hapi software (with git)
        • in correct directory
      • how to install libraries needed by our project
        (I sure hope this can be automated).
      • how to compile
        • might refer to Arduino dox with specific URL
        • augment with our own prose to cover what Arduino's dox do not
          cover.
    • on arduino hardware
      • how to download compiled software to it
        (might be able to refer to Arduino dox for some of this
        augmented by our own prose and/or programs)

The above should include prose saying what success and failure look like.
I have installed and run stuff on other projects,
where I had no idea if I had succeeded or failed.
As a newbie, I was completely clueless
about what was very obvious to the experts.

The above is just a rough outline.

It would be good to have one complete example based on a
minimum viable product.

Some things, such as downloading and installing the Arduino IDE,
can be done well by referring to a specific URL.
Some things have to be done manually,
and should be explained in prose,
sometimes augmented with pictures.
Things that can be automated, should be.
For example the prose of
INSTALL.rst
has a command
./INSTALL.sh,
to execute by manually typing (or copying and pasting).
The executed command, automates parts of the installation.

The docs do not need to be fancy.
Plain text dox that are comprehensive and accurate suffice.
We should be able to generate other formats, such as HTML, PDFs, and man pages,
from the source code for the documentation.
Sphinx
does this well with
reStructuredText.
Documentation source code in reStructuredText is readable as is
and the other formats can be generated from the doc source code.

---

By the way, this discussion started on pull request #106
and was moved here because the issue of documentation
is so much more than just the little code change in pull request #106.

[james-prior]

@matthew-dews wrote in pull request #106:

It is an unfortunate limitation that pull requests can't be opened on the Github wiki.

So commit the documentation source code in the same repo
as the regular (i.e., non-documentation) source code.

Also, consider generating the wiki automatically from documentation source code.
Documentation source code for the wiki might be in a separate directory.
Sphinx groks that very well.

[james-prior]

@TylerReedMC asked in pull request #106:

What instructions do we need?

See the top of this issue.

Step-by-step for setting up a node?

Yes, very much so.

We will have succeeded when a non-technical person that we do not know
is able to successfully use our stuff,
just by following our instructions on github,
without any coaching or hand-holding by us.

[james-prior]

@PedroSFreitas wrote in pull request #106:

Maybe this could shed some light: https://github.com/ozarchie/hapi/wiki/HAPInode

I'd like to merge Archie's Wiki with upstream,
but maybe @TylerReedMC would like to take a look first.

and later he wrote:

But a review is necessary

That is what the dev branch and pull requests are for.
Release early, release often.
Just throw the wiki into some directory (perhaps "wiki"),
add it to the repo and issue a pull request for it.
Maybe someone else will convert whatever form the wiki is in
to reStructuredText that Sphinx can automatically generates
web sites, PDFs, and more from.

[TylerReedMC]

@ozarchie turned me onto https://pages.github.com/ recently. We should take a look at it.

[james-prior]

I just added to the first comment of this issue,
that we need to document what success and failure look like.

Unfortunately, github does send notifications for edits to old comments,
hence this comment to review the top comment.

[matthew-dews]

I agree with @james-prior on using ReStructred Text and Sphinx. I think https://readthedocs.org/ is a good fit because you don't have to worry about styling or hosting. Readthedocs has versioning which will separate release documentation and development documentation.

I lean away from Github Pages because Markdown formatting may be limiting. In a previous project using Github Pages I found that I spent too much time customizing the theme I started with. I also don't like that Jekyll/Github Pages stores both content (Markdown files) and styling (javascript, CSS, HTML) in the same directory. I'd rather have everything styling/Jekyll related in one folder and leave the Markdown material easily accessible to developers rather than mixed in. This may not be possible to do with Jekyll or Github Pages because they rewrite config options.

I will have a chunk of free time tomorrow and could put together some sort of demo of readthedocs.

[james-prior]

@matthew-dews wrote about reStructuredText, sphinx, and readthedocs.org:

I will have a chunk of free time tomorrow and could put together something as a demo of readthedocs.

Fantastic! I look forward to it.

[matthew-dews]

@PedroSFreitas I am consolidating documentation as I work on this and I noticed that on the wiki the the Smart Modules are refereed to by two names: Smart Modules and HapiZ. Is there one I should stick with for clarity?

Edit: I am also seeing the use of the term HAPImodule and HAPInode

[moritz89]

Is this issue closed? As there has been a merge request

[PedroSFreitas]

I believe it's safe to close this Issue for now, but the idea of the Documentation proposed by james-prior should be take in consideration; maybe not all, but part of it. Information to possible users is never too much, in my humble opinion.

[moritz89]

More and good documentation is always something useful. Would break it down into smaller issues