
Show HN: Paperdocs, better documentation for the web - franciscop
http://francisco.io/paperdocs/
======
helb
Nice project! What was the main reason to build your own docs framework? Why
didn't you go with ReadTheDocs or some other widely used tool?

Some nitpicks:

1\. It would be nice to have an easy way to link to a specific (sub)section. I
see the heading IDs are already there, so maybe just add some small anchor
icons like [1]? Also, it might be good to change the anchor in the addressbar
when clicking a side menu item.

2\. It doesn't work without JS. I know it's common with a lot of websites
today, but software docs may be the thing people sometimes need to view in a
console browser with 80×24 resolution when the shit hits the fan… _EDIT: I see
you have a way for server-side render described in your Readme, that 's great.
:)_

3\. The print stylesheet could use some tweaking. Eg. these "Author Demo
Github" links take up a relatively large space and they are pretty much
useless on paper. Same with the menu heading and hamburger icon. [2] The links
are even overlapping the content on some pages. [3] I don't know how often
people print out documentation, but it might be a pretty common use case.

[1] – [https://vgy.me/MvofaK.png](https://vgy.me/MvofaK.png) – from Github and
ReadTheDocs

[2] – [https://vgy.me/a27pqw.png](https://vgy.me/a27pqw.png)

[3] – [https://vgy.me/RzRqxA.png](https://vgy.me/RzRqxA.png)

Screenshots taken in Chrome 56 on Linux.

~~~
franciscop
Thanks for all the interesting notes. One of the common patterns from
documentation I use is Ctrl+F and write what I want to search in real-time.
With ReadTheDocs and other _paginated_ documentation this is just not possible
and instead you have to adapt to their system. Also I feel like most current
systems are greatly oudated/basic ones, one of the things I like most that I
did in Paperdocs is the <nav> in mobile versions.

1\. I will totally do that.

2\. The recommended way in the documentation is to "render it server-side", as
in use normal html+css (or use some build system of your own). The "load file
through javascript" is nice but has some other problems such as SEO so it's
just an alternative.

3\. Also totally going to tweak it for print, right now there's nothing
specific.

------
franciscop
Author here, I have been struggling for long time to get decent documentation
across devices so I decided to get the best I had, improve it, package it and
release it. Please let me know what you think and what is missing for your
documentation needs.

------
ullarah
Might need to fix a few things, it seems you are trying to load scripts from
localhost. Not sure if that was intended?

<script src="//localhost:35729/livereload.js">

~~~
franciscop
Oops, totally missed that from dev, fixed

------
chrvadala
I will try it on one of my project

