Re: Zero Install documentation web-site

The current site does indeed seem bad on mobile. Do people want to
read it on their phones?

readthedocs seems a bit slow. Testing a refresh on one page at random:

Current site:
7 requests
47.94 KB / 27.70 KB transferred
Finish: 804 ms
DOMContentLoaded: 188 ms
load: 910 ms

New site:
22 requests
462.38 KB / 220.31 KB transferred
Finish: 3.25 s
DOMContentLoaded: 1.22 s
load: 3.25 s

It seems to add some tracking scripts and some adverts too :-/

I don't mind moving to markdown if people prefer that to HTML. It does
indeed give nicer previews on GitHub. On the other hand, I don't feel
we suffer from a lack of documentation at the moment.

In general, some things seem a little better (editing, separately
scrolling navigation, mobile) and some a little worse (speed,
tracking, ads, losing the search feature, non-folding menu, lack of
control over ordering).

In Sat, 25 Aug 2018 at 11:10, Bastian Eicher <[email protected]> wrote:
>
> Hi all,
>
> I finally got around to working on the idea of a shared documentation
> web-site based on http://0install.net/ and http://0install.de/.
>
> I forked https://github.com/0install/web-site to
> https://github.com/0install/docs and removed all non-documentation content
> (landing page, feeds, etc.). Then I moved and renamed files and directories
> to match the menu structure. Next I replaced the XSLT-based build system
> with the MkDocs (https://www.mkdocs.org/) static site generator. I believe
> this provides a number of advantages:
>
> MkDocs uses Markdown files as its input. Markdown is wildly popular for
> documentation these days, dead simple to write and has native support in
> many tools (e.g. GitHub's web interface). Speaking of GitHub, MkDocs
> generates automatic "Edit this page on GitHub" links.
>
> MkDocs comes with responsive themes, making the generated doc pages easier
> to read on mobile devices. I added some custom CSS to better match look of
> http://0install.net/. It also applies language-specific syntax highlighting
> to Markdown code blocks, which makes the XML and Python samples in the docs
> look nicer.
>
> MkDocs automatically derives the menu structure from the file and directory
> structure. This makes adding new pages very easy. It also detects and
> reports dead links between pages during build.
>
> I converted the HTML content of the existing web-site into Markdown using
> Turndown (https://github.com/domchristie/turndown). Then I went through all
> the pages manually improving the generated Markdown, adding code blocks,
> etc..
>
> Finally, I set up free automatic building and hosting using ReadTheDocs at
> https://0install.readthedocs.io/. This service also supports custom domains
> using CNAMEs, including automatically issuing TLS certificates. So we could
> serve this from https://docs.0install.net/ for example.
>
> Next, I will start integrating documentation for Zero Install for Windows
> from http://0install.de/ into this web-site.
>
> What do you guys think? Is this a viable approach? Any areas you think need
> improvement?
>
> Regards
> Bastian
>
>
> ------------------------------------------------------------------------------
> Check out the vibrant tech community on one of the world's most
> engaging tech sites, Slashdot.org! http://sdm.link/slashdot
> _______________________________________________
> Zero-install-devel mailing list
> [email protected]
> https://lists.sourceforge.net/lists/listinfo/zero-install-devel



-- 
talex5 (GitHub/Twitter)        http://roscidus.com/blog/
GPG: 5DD5 8D70 899C 454A 966D  6A51 7513 3C8F 94F6 E0CC