Single-page F3 site is less than ideal

[ssokolow]

While I definitely appreciate the many benefits of GitHub and I like being able to easily use Ctrl+F to search the entire F3 site, I think the current setup is less than ideal.

Here are the options I can see which would improve upon it:

1. Use the static templating support in GitHub Pages to split it back into pieces. Use something like Google Custom Search to add a search box.
2. Keep serving up the whole page but, when Javascript is enabled, style it as an accordion (all sections but the currently-selected one collapse into clickable headings) Add a TiddlyWiki-style Javascript-based search box which works like Ctrl+F but doesn't skip content marked display: none;.

Commenting in the style of the PHP documentation could be restored using one of the following methods:

1. Outsource comments to a Javascript-based comment system like Disqus or IntenseDebate.
2. Put up a GitHub Wiki page explaining when to use which tool, link to it, and use some mixture of the GitHub Issue Tracker, Pull Requests, and GitHub's per-line source code commenting feature. (Speaking of which, that last one is great for code review)

I'd be willing to try to implement one of these solutions for you if you're interested.

[ssokolow]

I don't see a problem with TW3 once it's ready but, given how TW2 doesn't really get along with search engines very well, it'd probably be better to wait on that.

The static templating using GitHub's Jekyll offering could be a good intermediate step though. Move all the common stuff into a template and prune the individual pages down to make something as close as possible to what would become the raw content of TW3 HTML-format tiddlers.

[ssokolow]

As I understand it, TW3 will support tiddlers written and stored in either wiki markup (for backwards compatibility) or HTML (for WYSIWYG editing and SEO). By moving as much as possible into a Jekyll template and CSS files, you could set up a Jekyll-templated site where the individual page HTML just needs the YAML Front Matter stripped off or converted (which can be automated) to be valid TW3 tiddler content.

As for starting, I'm in the same boat. I have exams to cram for and can't start anything until June.

[mattrobenolt]

What about Read the Docs ? They use standard Sphinx documentation, which is reStructured Text. Very common for hosting documentation. Built in search, versioning, etc. Really nice. :)

[ssokolow]

It does have those features, but it also has significant downsides...

• For security reasons, you can't supply your own templates. Unless you run Sphinx yourself and push the generated HTML to GitHub Pages, you're stuck with twiddling the colour schemes of the site templates they provide. (It's a documentation hosting site, not a website hosting site)
• You're locked into using reStructuredText and rST doesn't allow embedded HTML snippets. Even the copy of Jekyll built into GitHub Pages makes Markdown and Textile optional.
• The Sphinx/ReadTheDocs dialect of rST would only be relevant as an alternative to Markdown/Textile. They've only implemented Sphinx API-documentation constructs for Python, C/C++, and Javascript so far.

All things considered, it'd probably be better to just reverse-engineer the format of the index they generate and copy searchtools.js from a copy of Sphinx into your GitHub Pages site.

[mattrobenolt]

Yeah, I understand. I wasn't sure the full demands of what you guys are looking for, so I just threw it out there as an option incase you weren't familiar with it. I know it's used for just about any project in Python land, but us Python people don't care about how things look. ;)

[ssokolow]

@mattrobenolt: Python is my language of choice when I don't need PHP for the "runs on any web server" side of things. I'm well aware of every single wart Sphinx has. (Which is why I tend to use a mix of Jekyll and EPyDoc for my code even though EPyDoc is unmaintained)

For example, last time I asked about automatic documentation good enough to document functions and gather TODO notes automatically if I forget to add documentation for some new code, I was told that I was "wrong" for not spending 30% of my time maintaining my docs. Even if they insist otherwise, their actions show that Sphinx is a successor to LaTeX, not JavaDoc-style tools.

(I've actually sometimes found myself running EPyDoc or similar on Sphinx-documented projects simply because it's quicker and easier than reading the source to learn about method/function signatures for functions and classes they completely forgot to document)

[ssokolow]

I thought something felt off with "TW3" but I couldn't put my finger on it since, obviously, the version I'm running is 2.6.x so the next one "must" be 3.x.

The problem with any kind of comment system is that @bcosca will have to provide hosting for the dynamic portions. You can minimize the dynamic portion using a Disqus-style embed for dynamic comments, but there will always be a dynamic portion that has to be hosted outside GitHub unless you can figure out a way to use GitHub's API to use GitHub's Project Wiki feature as the backing store.

[ssokolow]

Keep in mind that FatFree is something that people can buy licenses to use without the GPL restrictions. I really doubt @bcosca would merge a pull request that would make it look like the project is such an amateur endeavor that it can't even afford a $5/month hosting account.

I'm all for not using Disqus, but it has to be something that would actually reflect well on the project.

[ssokolow]

Error 404 on that link. Got another?

[ikkez]

As F3 was hosting on SourceForge, the Docs were not only a single-page. Comment System was also there. But unfurtunately SF had massive problems with their server, whereby data were lost. Some of us talked about in IRC and comes to the point, that a static html version of the docs would be nice, as you can download it and also be able to use it offline and on the go. but a backend behind would be nice to make some crowdsourced translation possible... so a domain with backend is needed. but i would say, as long as king @bcosca does not made any decision, and we could also do that translation stuff with github, feel free to help writing the fridge docs. i'll add anyone to collaborators, who's willing to spend some time. me and the rest of the community really would appreciate your help. so far it's more a quick reference guide, with code examples to every method. I think it's the only thing that's really missing so far, as the F3 Docs page is still a good starting point and step-by-step introdution to all main features. Maybe some example use-cases would be nice, but could be done later. And who knows, maybe we could merge everything together into a new gh-page at the end.

[Jermolene]

Hi Chaps - thanks for linking me in. The next version of TiddlyWiki is called TiddlyWiki5, somewhat illogically. You can see what's going on at https://github.com/Jermolene/TiddlyWiki5

It now runs on the browser or under node.js. It's much more modular (everything is plugins apart from a 600-line boot kernel), brings graphics up to be a first class citizen (with integrated editting). There's also support for "exploded TiddlyWikis", where each tiddler is a separate file.

One scenario that might work well for you is to prepare your docs as a folder full of tiddlers and then use TW5 to "bake" different versions of the material: a static subset as a readme.md file, a read-only TW for distribution online, a big fat HTML file for Google etc.

[sn0opy]

Personally I would stick with FatFreeFridge. Okay, it's pure HTML, but we all know HTML and are conform with it. It's mostly easier to add new "features" with CSS for a single paragraph.

Aside of that, we could also stay with the Github Wiki which has syntax hilight for code and Markdown. The only problem, it's confusing.

[ssokolow]

@sn0opy: Why not just use the Jekyll templating offered by GitHub Pages then?

You get to keep using plain old HTML, but you can also share a common template file between different pages and use variables to substitute things back into it like the page title (and the gh-pages branch will contain the un-templated source, rather than the generated results, which makes it good for collaboration).

You also get to use {% highlight php %} ... {% endhighlight %} to colorize code using Pygments. (Just applies CSS classes. Color scheme is fully customizable.)

If end users want a local copy, someone can easily run jekyll && zip -rTm f3_docs.zip _site on their own machine or in a cronjob or GitHub HTTP POST post-commit hook on their web host.

[sn0opy]

Do you have any nice examples of projects using this way for their docs?

[ssokolow]

I remember running across some, but I'm having trouble remembering which ones. I tend not to remember that sort of detail unless I think it will be relevant at the time.

The few minutes I can spare right at this moment turned up this example though: https://buildr.apache.org/

They use Textile as their markup language for individual pages, but it's really no different than doing it with HTML. Jekyll just feeds the file through a Markdown or Textile processor before working on it if the extension matches one of the ones on its list.

[ssokolow]

Oh, if you want a really simple example of how a page's source would look under those circumstances, the FAQ from one of my projects would do:

https://github.com/ssokolow/quicktile/blob/gh-pages/faq.html

The result is here:

http://ssokolow.com/quicktile/faq.html

[sn0opy]

I will stay with @ikkez Project first. Just modified a bit yesterday.

http://ikkez.github.com/FatFreeFridge/examples_en.html

[Jermolene]

I think TW5 is already pretty usable for your purposes. I've been purposefully staying away from UI polish at the moment, to discourage premature adoption by end users, but I'm sure you'd be fine with it. TW5 uses the same Twitter Bootstrap styles that you're using, so you could hopefully carry across your existing styling easily enough.

If you download the TW5 repo you'll find a batch file bld.sh that does most of what you want: it runs TW5 under node and loads up the tiddlers in the current working directory, and then subsequent commands save specific tiddlers as files. You'll see how I create a readme.md for GitHub by processing a tiddler called ReadMe that consists of transclusions of a bunch of other tiddlers. Saving the full, JavaScript-y TiddlyWiki file for the browser is also just a matter of rendering a template tiddler that includes macros that pull in the tiddlers that should be included in the file.

I'm very keen for TW5 to find a niche as a revision control-friendly project documentation tool, and so would be happy to try to help knock it into shape for you.

[Jermolene]

Hopefully there'll be a more or less complete beta around July, and I'm aiming for a full 1.0 release in September.

[ssokolow]

I'm willing to help once I've unwound a bit from exam time, but I'd still rather see the documentation hosted on GitHub Pages if feasible. That way, it stays near the code, it's easy to collaborate on, and you don't risk having code without readily-available docs because a free host lost or decided to delete your files without telling you.

[ssokolow]

@GHANONTEST Actually, the exams should be over by the end of today (I'm about to go to sleep so I can wake up and go to the last one) but I'll need a week or two to unwind before I feel comfortable committing to anything. Committing to things too early in my break was what made it almost impossible for me to relax last summer.

As for the content, I see no problem hosting either a comment system or the whole thing elsewhere as long as there's a copy versioned on GitHub. Ideally, either a copy of TiddlyWiki that's both diff-able and viewable or a cronjob-rendered dump of something else with "This is a static mirror. Live documentation can be found at _____." headers. (Preferrably also containing a dump of the raw markup it was rendered from in case the worst does happen to the live site.)

[ikkez]

Well, TiddlyWiki really might be a nice project, but i cannot befriend with it so far. At first sight it just looks overdressed for our purpose and causing additional hosting and duplicated repo with inconsistent data integrity. If you're only want a comment system and some templating, the Jekyll engine could split up files and comment system can be hosted anywhere,.. we could load and save entries with some lines of JS. Using github as version control fits best IMO, and hosting where the code is (gh-pages) is also fine. so why make it complicated!?

the other thought i have is that doku or tw will encourage contributions from those who have no idea what git is.

i would venture to say that people who are not familar with git or any gitApp, are also not as familar with F3's source as it would be required to write quality doc input. And by the way you'll have to check all articles and changes afterwards, need to learn another markup, have to rely on outsourced hosting and still have no base for a possible new website, which is a bit eye-catching to gather some new follower to F3. Look at jQuery e.g., it's a doc, wiki and product-page in one. That is the way, we should to go to.

[sn0opy]

Im fine to see a working copy of TW5 with some of F3's examples. But for now, I will stay with @ikkez project.

[ikkez]

what a big reading this late at night. well,.. i just don't wanted to lock myself from communicating. i think i could not imagine, how it feels at the end. But well... why not,. give it a try. Will you merge the fridge layout to TW and handle the setup? Seems like you've already worked with it ^^ Shall we add a new branch or is it better you fork it? next TODOs? more later, sleeping now *Zzz

[ssokolow]

@GHANONTEST

the Jekyll engine could split up files

[...] There's actually a plugin for dokuwiki that lets it adopt markdown as its wikiparser. That would be the same format used for issue comments like the one you just typed on github.

For the record, Jekyll also takes Markdown and Textile as alternatives to HTML. Just use .markdown or .md or .textile as the file extension.

I hate to beat a dead horse, but I feel like we're just not communicating.

I get the impression that the problem is mismatched values. For example:

• I've run across quite a few projects where some aspect of the site's infrastructure was down because it was the only piece hosted on private hosting rather than GitHub or Google Code or the like.
• I actually see a wiki as a downside because they're much more prone to either being defaced by the new spambot that can get past yesterday's CAPTCHAs or edited impulsively by novices who don't know what they're talking about. I see a lot of project sites where, to read them, you first have to revert the spam.
• GitHub Pages is static. If your comment system is the only dynamic part of the system and it lacks write access to the rest of the system (either through permissions or by being a Javascript embed from a different domain), then only the comment system can get hacked as long as GitHub's HTTP daemon doesn't have any exploitable vulnerabilities.

I understand what you're saying, I just don't value the same aspects you do.

[ssokolow]

1. Still, I'm just generally wary of any solution that hosts different parts of a project's user-facing infrastructure with completely different organizations. Plus, GitHub makes their money by selling to companies. That means they'e got an obvious, up-front, monetary incentive to have high uptime.

   Also, I'm generally wary of any company that doesn't make it clear how they're covering their costs. None of the three freehosts you've mentioned say anything about that.

2. You didn't say anything about how I also consider the non-wiki nature of GitHub Pages a feature because it filters against edits by users who are too green to know what they're talking about.

As for #2 and #3 from the spam and hacking front, it's more that if GitHub Pages can be made to do what we want fairly simply, why should we leave an open invitation for trouble on several fronts?

[ssokolow]

wary of any solution that hosts different parts of a project's user-facing infrastructure with completely different organizations.

<flame> IF YOU WANT COMMENTING THEN THERE IS NO WAY AROUND THIS EXCEPT TO HOST ENTIRELY ON HELIO WITH DOKU. WE NEED A SCRIPT HOST FOR PHP COMMENTING MECHANISM, SO WHETHER ITS DISQUS - EWW - OR TILDEHASH, MOVING THE MAIN DOCS TO GH-PAGES FRAGMENTS EVEN MORE :P

Actually, what I meant is that I want the following to be hosted on the same platform:

• detailed product description (website)
• screenshots or, for a library/framework, example snippets (website)
• release downloads
• source repository
• manual (task-oriented and end user feature-oriented documentation, as applicable)
• API documentation (internal feature-oriented documentation)

Those are what I consider "the product" as a whole and breaking it up annoys me just as it annoyed me when I used to buy CD-ROM games and the level editor was a download because they'd slipped a deadline.

The rest is either "the developer tools" or "the community" and can be hosted separately.

I really like comments (I avoid news sites without them) but the only site where the comments are really essential at 5 in the morning when you have a deadline is PHP's site and I despise them for having a language where essential documentation and/or functions which should be part of the standard library instead live in the comments.

But yeah, it's run by volunteer hobbyists and funded out of someone's pocket as a public service.

Hmm. In some ways, that makes me more wary. With a site like GitHub, I know where their money comes from, I know it's not going to dry up, and I know it's in their best interest to keep the site going. With "paying out of pocket", whoever owns the pocket could fall on hard times right when we're too busy to spare the time to properly find a new home.

I just don't really see it as an open invitation. Regular backups are always a good idea, and restoring the doku directory image isn't a problem. I don't think there's all that much trouble to be had unless i'm missing something.

"Green" is a bit of slang from the United States that Canadians like me picked up. It's a metaphorical reference to "green wood" and means that someone's still very new and inexperienced with something.

Personally, I see anything "wiki" as an open invitation for trouble unless the project has a certain critical mass. Sooner or later, one of two things will happen:

• A site or the technology it's based on will get popular enough for some spammer to write a bot to exploit it.
• The administrative burden will grow as more novices decide to contribute... potentially exceeding the manpower available.

I think I might have identified why our values are differing. I'm envisioning something more like an official manual while I get the impression you are thinking more of a community wiki. What I'm envisioning, by definition, has stricter standards for quality-control.

Maybe we could make both and then focus on polishing up and integrating wiki content that looks like it fills a hole in the docs.

[ssokolow]

http://fatfree.sf.net// is already a redirect to http://bcosca.github.com/fatfree/ but @bcosca seems to have forgotten to update the homepage link on the GitHub project page.

Since the F3 site is already using GitHub Pages, my recommendation would be to get everything (including the official single-file docs) cleanly and appealingly merged into Fridge and then offer it to @bcosca as a proposed successor to what's currently offered.

[ikkez]

+1

[bcosca]

I'm with whatever the consensus is. After all, this is a community-supported framework.

[ssokolow]

Perhaps, but keep in mind that Firefox overrides the / key for its own find-as-you-type search.

I've heard they plan to remove that keybinding it, but the Chrome devs' refusal to add it was one reason I switched back to Firefox from Chrome and I'm sure many other people including myself will install Firefox extensions (if necessary) to restore the Vim-style search keybinding if/when they do remove it from Firefox.

[ssokolow]

My issue is that, as implemented in that site, it tells you to use / to trigger THEIR behaviour, even though Firefox intercepts that key for its own purposes.

I have no problem with that kind of find-as-you-type search. I just think the UI needs work so it doesn't give confusingly broken instructions.

Also, keep in mind that I'm on Firefox Aurora. That means that, if the Firefox devs decided to put their feet down and remove that keybinding tomorrow, most end users wouldn't see the change until at least 12 weeks after I saw it... and that'd still have to wait for it to arrive from Nightly, which can take up to 6 weeks. (And it's possible they've changed their minds. I haven't heard any mention of it in a while.)

[ssokolow]

Oh, and yes. I agree that it would be a good idea to split all this off into separate threads on FatFreeFridge's issue tracker for now.

[ssokolow]

@GHANONTEST I don't like that solution. It's un-diplomatic enough to reflect badly on F3.

In fact, I've been trying not to mention it, but I might as well rip off the band-aid quickly and get it over with. That's part of a bigger problem with being tactful that you might want to work on. As is, I keep feeling as if I'm talking to someone who just graduated from high school. (The direction you've been arguing from in the HAML issue has the same problem.)

In this case, the problem is that standards aren't the be-all and end-all. In fact, to the best of my knowledge, there's no accepted browser standard that says a compliant browser must leave certain keybinds open to the site. (There's probably one being discussed, since the web is becoming an application platform, but not yet.)

Technically-skilled Firefox users tend to be touchy about any indication that a site is, through action or inaction, trying to aid the mobile-inspired threat of a new WebKit-based "Internet Explorer 6.0 is the web" era.

Also, even if there was such a standard, Firefox has had that keybind since before Chrome and Safari existed. In fact, I suspect it's been there since Firefox was called Netscape and its only major competitor was Internet Explorer.

By claiming that Firefox's keybindings are a standards violation, Firefox developers and users are likely to see you as implicitly looking down on them for not being and doing what, in your subjective view, is the one correct thing. (It's like saying "You use a trackball rather than a touchpad. That's a standards violation." or "Your car is brown, therefore it doesn't comply with automotive safety standards" when, really, everyone else hears "I'm an immature person who thinks your way is stupid/ugly but doesn't want to just come out and say it.")

Yes, common functionality is good, but requiring every browser to do everything exactly the same just shows that you're a rigid and/or lazy developer who isn't willing to make a reasonable effort to acknowledge that different users do things differently.

[ssokolow]

The WHATWG is just made of humans like anyone else. Whoever set that up probably just wanted to get it up and working and didn't think to ask everyone to hammer on it to find shortcomings. (The "better flawed than not at all" approach to agile site updates, as I like to think of it)

[ssokolow]

@GHANONTEST

It felt a bit too much like you weren't giving proper consideration to other peoples' points of view before dismissing them and reaching for whatever edge you perceived as potentially letting you have your way.

[ssokolow]

@GHANONTEST: I have no problem with that.

[ssokolow]

@GHANONTEST: Actually, ?q=%s would be better. It's more semantically correct and modern Javascript can still access and manipulate it without requiring server-side code or full-page reloading.

#search/%s also tends to get tripped up by software which assumes it's a intra-page link. (For example, StumbleUpon, which strips fragment identifiers when you use the "send this page to a friend" function)

[sn0opy]

I think there's a more elegant way to do this, but you can fake everything in the url bar with HTML5's "pushState" Javascript function. So everything in the url bar is actually not "real" just modified.

[ssokolow]

@sn0opy history.pushState is the more elegant way.

@GHANONTEST: The query portion of the current URL can be accessed in Javascript using location.search.

As for setting the URL without reloading the page, the simplest solution is to do some feature testing. If the browser supports history.pushState and isn't Safari (too buggy), then you use it.

If not, then you set and read the fragment portion of the URL using that #!.... form that Google proposed rather than #.... so it doesn't conflict with any real fragment links you might use.

As for app caching, I'll have to look into that, but it seems like a pretty big oversight for it to be incompatible with history.pushState, given the purpose of the two technologies.

[ikkez]

boring Don't we have any more important topics about the docs, than implementations of seach addons? We need a better and complete doc page first. Without docs, there's nothing to search for. For me, this discussion feels like doing task No.5 before No.1 is done.

[ssokolow]

@GHANONTEST: The ?q=... would be ignored by the GitHub servers and the UA-side JavaScript would be able to read and act on the contents via location.search and, in modern browsers, history.pushState. Try going to any page on the web with a query portion, opening up the browser's JavaScript console, and typing these two lines:

alert(location.search);
history.pushState({}, "", location.origin + location.pathname + "?SUP_FOO");

Modern browsers give Javascript full support for reading and writing the URL (subject to same-origin restrictions) without reloading the page. (You'll also notice that, if you then click the Back button, it doesn't reload the page. Entries added by history.pushState instead fire a Javascript event and expect you to implement Back functionality.)

As I said, the only time you need to use the hash/fragment identifier is as a fallback on older browsers and Safari, where history.pushState is buggy. There's a plugin to make that simple too.

@ikkez I've just been really busy lately, so all I've had time to do is converse on the issue tracker.

[ssokolow]

@GHANONTEST:

GMail has an annoying tendency to try to circumvent browser designs unless you make properly sure that it's incapable of it. If it really does hijack '/' (I access mine via IMAP), then that's one more reason for me to hate recent iterations of the UI and one more Greasemonkey userscript I'd need to find or write.

Just because you've found a way to force your will on the user doesn't mean they'll like it.

[ssokolow]

@GHANONTEST: Point.

I'd still be cautious about hijacking anything with a default browser behaviour though. From a UI/UX design standpoint, you want to only hijack a built-in behaviour if you're implementing a superior variation on it.

...and I'm not sure "search all pages" counts as a superior variation of "search visible content". It'd be like Hijacking Ctrl+F on Wikipedia to move the cursor to the whole-site search box, rather than letting you search within the article.

(To people used to '/', myself included, it'd be an unpleasant surprise for Ctrl+F and '/' to suddenly do wildly different things if they are unlucky enough to have their muscle memory set to the wrong one.)

[sn0opy]

Guys, sersiously. It makes absolutely no sense talking about a stupid function to hijack some keys w/o even having the content. Usability kan be done after the whole docs are written...

[ssokolow]

@sn0opy: I believe I mentioned before that I don't have time to write docs right now. I can shut up or I can spend 30 seconds responding to the one additional e-mail in my inbox each time I check it.

Either way, it's not going to grant me time to work on the docs because of the fixed time costs involved in getting into the right state of mind because I'm busy studying for a test related to getting my driver's license. (I've spent nearly 10 years without one because of budgetary concerns.)

Therefore, I might as well discuss usability now, rather than spending that 30 seconds doing something not related to F3 in the slightest.

[ssokolow]

@GHANONTEST: Point, but my exaggerating the degree of difference doesn't change the fact that people react badly to having their expectations broken.

[stevewasiura]

Can we create pages in FatFree's Wiki? I added a GH wiki page to my fork, but when i tried to issue a pull request, it said my fork was identical. Is this something @bcosca has to open permissions for?

[sn0opy]

I think you requested the pull for the wrong branch.

On Friday, October 19, 2012 at 3:31 PM, Steve Wasiura wrote:

Can we create pages in FatFree's Wiki? I added a GH wiki page to my fork, but when i tried to issue a pull request, it said my fork was identical. Is this something @bcosca (https://github.com/bcosca) has to open permissions for?

— Reply to this email directly or view it on GitHub (https://github.com/bcosca/fatfree/issues/2#issuecomment-9601007).

[stevewasiura]

maybe, but i only see 2 branches, fatfree, and github pages. neither of which has any wiki pages (whenever you click on wiki pages tab it redirects back to the code tab)

I think @bcosca may have a checkmark set in his GH admin for the wiki that restricts wiki mods to collaborators only, hence why I cannot do a pull request to pull in my wiki page add.