<div dir="ltr"><div class="gmail_extra"><div class="gmail_quote">On Wed, Nov 23, 2016 at 4:24 PM, Allan Day <span dir="ltr"><<a href="mailto:allanpday@gmail.com" target="_blank">allanpday@gmail.com</a>></span> wrote:<blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div class="gmail_extra"><div class="gmail_quote"><span class="gmail-"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>I propose to improve the main flatpak website adding a  documentation section, something like <a href="https://angular.io/docs/ts/latest/" target="_blank">Angular's website</a>, or <a href="https://ionicframework.com/docs/v2/" target="_blank">Ionic Framework</a> or create a manual at readthedocs like <a href="https://ostree.readthedocs.io/en/latest/" target="_blank">OStree.</a> (some of the information in flatpak's wiki is in Markdown already so most of the effort won't be wasted)<br><br></div><div>I can help setting up the things (readthedocs, jekyll, ...) and organizing a little bit the docs, but I would like to have some help (I'm not a native English speaker)<br><br></div><div>What do you think?</div></div></blockquote><div><br></div></span><div>As time goes on it is likely that we will need a more advanced method for hosting and organisatiing the developer docs [1]. Are we at the point where we need to do that? I'm not sure.<br></div></div></div></div></blockquote><div><br></div><div>Having thought about this some more, I think I agree that we need something more sophisticated for hosting our documentation. It would help to have a way to quickly navigate between sections, and a multi-page approach would be more sustainable than a single big tutorial. Search would also be good.<br><br></div><div>We don't have much web maintenance capacity, so whatever option we go for needs to be quick and easy to setup. readthedocs is an obvious option. Yesterday I had a go at putting our existing Markdown docs into it: <a href="http://flatpak.readthedocs.io/en/latest/">http://flatpak.readthedocs.io/en/latest/</a><br><br></div><div>It's certainly easy to setup and has good integration with Github - you just push your changes to the Git repo and the documentation automatically updates. People can also download your docs, and you can version them.<br><br></div><div>The main issue I found is that search doesn't seem to work when using MkDocs/Markdown (probably because of this [1] bug). readthedocs recommends using Sphinx/reStructuredText [2] instead and it looks like search would work if we ported over to use that instead. I have some reservations about that, though.<br><br>Does anyone know of any alternatives that we should consider?<br><br></div><div>Allan<br></div><div><br>[1] <a href="https://github.com/rtfd/readthedocs.org/issues/1487">https://github.com/rtfd/readthedocs.org/issues/1487</a><br>[2] <a href="http://www.sphinx-doc.org/en/1.5.1/index.html">http://www.sphinx-doc.org/en/1.5.1/index.html</a></div></div></div></div>