
Show HN: Sodocan.js: Documentation Made Easy - serrisande
http://www.sodocanjs.com/
======
codebeaker
A shame that the page has to hijack the scroll functionality, it makes for a
very unpleasant "lumpy" feeling scrolling. Chrome Version 46.0.2490.80
(64-bit) on OS X Yosemite.

~~~
serrisande
The parallax scrolling on the landing page does seem to go a little too far.
We'll fix it soon. Thanks!

~~~
Kiro
Not sure it's related to the parallax. It's more about the scroll hijacking
which makes it very unpleasant on Mac using a Magic Mouse. It's really
obviously broken so I'm pretty sure no-one in your team has one or else this
wouldn't have been shipped.

The product seems interesting anyway!

~~~
oneeyedpigeon
Yup, it makes for a really horrible experience - like wading through treacle.
I think this page officially marks the point at which scroll-hijacking has to
stop!

------
liujoycec
If you would like to some real examples of documentation created using
Sodocan.js, check out
[http://jesterswilde.github.io/hashids/](http://jesterswilde.github.io/hashids/)
and [http://liujoycec.github.io/jwt-simple/](http://liujoycec.github.io/jwt-
simple/) . These are both created from the Blueprints template Sodone. These
templates are also open-source, and we would love for you to help us improve
them and add more templates!

~~~
lhorie
First impressions: feels rather unpolished

\- text is too light and hard to read. Color contrast between text and
background could be higher.

\- up/down arrows do nothing

\- plus button shows login dialog, but you can't register from there

\- TP/EX/DE buttons are not in same order as their respective sections

\- missing alt text on icon buttons, so it's not clear what they do (or
rather, what they're supposed to do, since some do nothing)

\- like button shows wrong cursor on hover

\- buttons in settings dialog do nothing

\- example has no code highlighting when present

~~~
serrisande
Thanks for your input! Some button don't do anything right now because there's
only one entry for the category, and certainly having tooltip will be able to
help with the confusion the UI causes. We have opened github issues for the
rest.

~~~
lhorie
If pressing a button will do nothing due to lack of content, it should either
be visibly disabled or hidden

------
IanCal
This looks really interesting, thanks for sharing.

I'm finding it quite difficult to read through the main page however, as
there's something going on with the scrolling. It's hyper-sensitive, then when
there are animations on the page they play through before jumping me really
far.

~~~
serrisande
Thanks for pointing it out - the parallax scrolling on the landing page does
seem to go a little too far. We'll fix it.

------
graffitici
I'm trying understand what this fulfills. I understand it extracts
documentation from comments, and writes them to a JSON file. There are have
been countless tools to do this.

But the difference of Sodocan is that it then sends these JSON files to an API
server, which hosts these documentations?

So basically instead of using JSDoc + static site generator, one would use
this method?

And the benefit would be that the generated documentation would be
crowdsourced?

~~~
serrisande
That is right - so the idea is that the project owners don't have to be the
only ones to maintain the documentation, instead the users can contribute as
well. The same project hosted at different places all point to the same place
in the database. We also plan to add version control.

~~~
graffitici
I see. But shouldn't documentation in the source code be the "only source of
truth". Say I upload the documentation JSON file, and somebody else edits it
online. If I re-generate the documentation from the same source code, I will
no longer be able to push the changes, right?

Also, is there a demo view, as to what the generated documentation looks like?

Great project!

~~~
serrisande
Thanks! To see a demo, please visit
[http://jesterswilde.github.io/hashids/](http://jesterswilde.github.io/hashids/)
and [http://liujoycec.github.io/jwt-simple/](http://liujoycec.github.io/jwt-
simple/). As some other people have pointed out, the font is too thin and the
contrast is difficult to read which is fixed by the most recent PR to the main
repo (the demos haven't been updated yet). Please check back for the updated
demos!

------
iamleppert
I used to be of the camp that excellent documentation for your code was a
necessity. All that pretty syntax and comments above every function
declaration. It made me feel like putting icing on a cake...I still agree this
is required for public facing APIs and stuff offered by a company or a
complicated project.

But documentation is only part of the story. You really need a full team of
smart technical people, writers, and "dev evangelists" that are creating
sample projects, tutorials, quick start guides, and giving feedback to the
engineers on how easy their APIs are to use and understand. You can't just
auto-generate docs and think you're done.

That said, I much prefer open source projects to be organized logically and
the code to be "self-documenting". Don't make me wade through mounds of API
documentation when I usually just end up going to the source anyway to figure
out what's going on.

------
liujoycec
Thanks for all of the feedback! This project is in the early stages and we
appreciate you letting us know what we can do to improve it. It's open-source,
and we are very excited that there are already developers submitting pull
requests to improve the user experience, and we encourage everyone to help!

------
amelius
I think it is a shame that most projects have only documentation in the form
of one-liners for each function/variable/class. Those one-liners really don't
mean much if you don't have a picture of the global architecture in your mind.
That is far more important.

~~~
drone
This is one of the things I really like about Doxygen, the ability to
automatically generate relationship maps between libraries and inheritance.

~~~
serrisande
This is something we plan to include in future releases as this is still a
project in the early stage. We welcome your contribution!

------
jand
Ok, what is the unwanted side-effect for the user? Since i cannot see pricing
info or such - how do you monetize? Which part of my soul - as a user - do i
sell by using the service?

And: The service looks nice - my way of asking questions does not imply a bad
impression.

~~~
serrisande
This is an open source project hence there is absolutely zero monetization.
That said, please fork us and contribute! :)

~~~
jand
Thank you for the answer, my bad.

------
lancefisher
I was curious about some of the tech stack since there is a section on the
landing page. I recognize most of the logos, but some I don't. It'd be nice if
there were links or even names on hover, instead of just one big image.

~~~
serrisande
Good idea. Thanks!

------
juhq
Oh boy that scrolljacking :(

Please, no more of these. Scrolljacking is a real turnoff each time, it's a
huge distraction.

Can we please kill scrolljacking before 2016?

------
trymas
Scroll hijacking in your landing page? Why?

Am I the only one, who cannot believe that websites made by (web)developers
use scroll hijacking?

------
Gigablah
I find it frustrating to read the documentation demos you have created. Low
contrast and poor choice of font. This is what it looks like on Chrome in
Windows 7:

[http://i.imgur.com/ArFcnM2.jpg](http://i.imgur.com/ArFcnM2.jpg)

~~~
serrisande
Another github user has submitted a pull request to fix the contrast. We will
update the demos momentarily. Thanks!

------
winterlight
There's a typo in the "What is sodocan.js" lane, right at the bottom of the
2nd paragraph.

natuarally => naturally

------
sdtsui
Hey there. Where could an OSS project owner find a 'getting started' guide?

~~~
liujoycec
Thanks for your question! The 'Getting Started' guide can be found in the
Github repo README at
[https://github.com/sodocan/sodocan.js](https://github.com/sodocan/sodocan.js).
We will update our site to make that link more prominent.

------
yclept
is it compatible with jsdoc?

~~~
serrisande
Not presently, however that is something we are thinking about. Our native
parser does take jsdoc-like syntax.

------
lekeve
This is awesome!

~~~
serrisande
Thanks. This is still a project in progress so please fork and contribute on
Github!

