Wiki Documentation?

[vdachev]

Wouldn't it be better if it was a Wiki based documentation, so that they're more contributors, discussions, links between articles, etc.?

[silently]

I don't know the magnitude of "more" that you expect, but having the doc both served and authored on github pages is the very reason for that: open issues, make pull requests, discuss them, keep track of them... Many people are already on github and won't have to create an account (moreover we will eventually open the platform source code, so everything will be public on github).

The different sections are listed here https://github.com/ozwillo/ozwillo-doc/tree/gh-pages/_includes, you can fork the repo and edit the pages in markdown.

On another topic, I personally like the "one page" documentation so that I can search for a keyword and be sure I am not missing an important bit of info. If it grows too much, maybe we won't be able to keep this.

And finally, please note the doc is responsive!

[tbroyer]

@silently – How about adding "edit this section" links to each section, leading directly to the edit page on GitHub? We have such links on gwtproject.org (e.g. http://www.gwtproject.org/doc/latest/DevGuide.html, notice the GitHub icon next to the title) and it really increased the rate of community contributions!

@vdachev – if your concern is the ease of contributing, see my suggestion above, but we don't want anyone to be able to edit pages right away, there must be approval and pull requests are great for that (and a tool every developer should be familiar with). If it's about syntax, well, it's markdown, so wiki-style besides links (and that really is a detail if you ask me; YMMV). Otherwise please explain.

I don't share @silently's take on the "single page" doc as I think it unnecessarily complicates the site maintenance with little to no gain (if you want search, just drop in a Google Custom Search widget or equivalent); but let's see how it plays out before spending time "refactoring" everything.

[vdachev]

@silently , I don't find doc.ozwillo.com responsive. It zooms, yes (although, if I zoom too much on my phone, the index and the content overlap), but that's not responsiveness - it's also smart placement of different components on the screen, depending on its dimensions. Also, having a dedicated markup guarantees a uniform view of different components, syntax highlighting, etc.

@tbroyer , it's not only the contribution in sense of editing (it could be enabled for a closed group of contributors) but also discussions, version history, comments.. Do you really have to go back and forth between the site and GitHub for all of that?

[silently]

ok I forgot some meta tags settings, can you re-check now? Please share a screen capture if still not responsive, plus your OS version. Thanks!

In the doc, we have only one column of contents, see it as a book, plus a menu/sidebar. So no fancy 3-columns based switching to a stack on mobile. We're in a stack mode everywhere.

[vdachev]

Moreover, in the current single-page documentation:

• How do I get a hyperlink to the section of the document I am currently in? Should I really find it in the index and click it in order to get the link?
• How do you maintain hyperlinks between different sections, changed links, etc.?
• Should all the documentation be loaded at once, just to find a certain piece of information? What about the loading time?
• Is Ctrl+F a better search engine than a full-text search of a Wiki?
• How do I point to a certain section of the documentation to report an issue, if there's no easy way to get a link to it and the index is not numerical?

[vdachev]

This one represents the page when I initially load the page:

This one represents the page when I zoom it out:

I find them both inadequate.

[silently]

I don't want to justify choices as if they were fixed in stone, since they are not.

I've opened an issue for two of your remarks: https://github.com/ozwillo/ozwillo-doc/issues/5

Regarding the hyperlinks, they are prefixed with the number of the main section and then there is a more textual description so that the URL is a bit descriptive. Similar example here. There is no policy right now to ensure anchors are permanent, maybe there should be one and so the section prefixes should be removed so that we can refactor the doc (like adding new sections). I would be glad to hear @tbroyer opinion on this.

About the loading time, please share numbers. There are pros and cons to the single page thing. For instance, if you have a bad connection, you will be glad to reduce HTTP requests. I am not trying to convince you, I just want more people giving their opinion. Anyway, as the doc enriches, it seems having several pages will help.

Finally, I am not sure answering yes or no to the Ctrl+F question would help.

[silently]

Regarding screenshots: why is the first one inadequate?

[vdachev]

@silently , in the OpenID Connect Core, there's an index you can get the link from. In fact sections may grow bigger with populating the documentation, and I suppose the index will grow (as the one on OpenID Connect Core) already has. And while on this example, OpenID Connect documentation is also split into several documents and it's Ozwillo is significantly bigger (I think).

Loading time depends on the connection. If you're using mobile connection, it could be slow. Or pricy. It's not the number of HTTP request - the HTTP request/response headers' overhead is relatively small compared to the text.

About the Ctrl+F, that's in response to your statement that "[you] personally like the "one page" documentation so that [you] can search for a keyword". You can do so with a normal full-text search, but there you can search for much more than just a keyword. If I, for example, search for "User object", I would get much more than the exact phrase, as well as the title of the found "section" and a part of the text the phrase was found...

[vdachev]

Regarding the first screenshot, the text is clearly out of the window. That's why I started zooming out in the first place.