definitelytyped.github.io
definitelytyped.github.io copied to clipboard
DefinitelyTyped
Add browsable index
Like the on on TSD site.
Needs new TSD internals (current one skips a few definitons, like the ones with extra subdirectories).
Needs a webhook to update a JSON on each merge. And also some reliable hosting for the JSON. Current TSD one is manually updated but it is not sustainable.
Usable for #12 too.
Thinking about the content and it's structure on definitelytyped.org I was pretty amazed that there is no package index. Most others (bower.io, jamjs.org, gruntjs.com) offer a section like that and I'm pretty sure it will be the first thing people are looking for on a repository website.
"Like the one on TSD site."
To find a package index on the tsd site, which is actually a sub-page on definitelytyped.org but looks completely different, has been even more confusing.
Simple question: Could we merge the two sites?
The TSD website existed more then a year before definitelytyped.org was imagined. I made it black & cyan when I published TSD 0.5.x, and after we later got the dt.org nobody got around to moving the stuff over and making it fancy.
Also https://github.com/borisyankov/DefinitelyTyped gets more then 10x traffic compared to definitelytyped.org, many folks just rummage around there.
Anyway, our designer was working on some designs, but it is very slow moving.
If you feel a need to do a quick fix until then I guess you can fork this repo and make it work with a quick copy-paste and some magic sauce. Right now it is some simple Vue.js thing made in a day, but I guess you can just paste that in the right file somewhere in the docpad stuff.
The data is a single fat JSON file generated by TSD's api.
For the TSD micro site we then remove this table and I think we just add the README (but in cyan on black to keep it distinct from main DT stuff).
Oh, forgot to add: I got a TSD 0.6 here that works better with caching. It could run on a server and update the JSON every few hours without hurting bandwidth too much, but I never got around to setting it up (some minor stuff to figure out and too much other stuff to do :).
So it's more a kind of political decision to keep both sites separated? I have to admit that I also just copied the definitions directly from GitHub till know, but I'll guess if definitelytyped.org becomes a bit more polished it'll attract more users and, in the end, hopefully makes using DefinitelyTyped a bit more streamlined. Would be great to have a searchable index of the packages with direct download link and copy and paste tsd command.
Anyway, our designer was working on some designs, but it is very slow moving.
Is there some sort of discussion group where one may find information on the new design? Are you working on a kind of theme for the current page or will you revamp the entire site? I have some ideas that would involve moving parts of the site around, especially as the site would become bloated if we integrate the package listing. However, it would make more sense to discuss UI and structure together.
Just forked and pulled the repo, looks very handy. I would like to contribute but I'm a bit of afraid to put work into a quick fix if there is a big overhaul coming anyway.
Sorry for all the questioning.
Well, glad to see some interest, I'd like to play ball on this.
Group is not so active here, current web property is mostly setup by me feeling a need (with some okays and content editing by others) :smile:
@diogorodrigues is doing some design stuff, moves a bit slow. status is unclear. I think it is mostly a skin type thing but that is not really decided. If you have a good plan then feel free to post it in a new Issue and we can ping everybody who is not already watching this repos.
Anyway there is no real decision or group politics, things just.. happen (or not), when somebody has time and a drive.
My view on structure is that the DefinitelyTyped Git repos is the core activity/product, most action happens there. The DT.org site is basically there to support that with extra info, like the contribution guide, best practices etc. The TS-directory is something we had in another repos, but I put it on the site as filler (with the hope someone would update it).
The NuGet export and TSD are like side activities, not really core stuff. NuGet exporter 'just works', nothing too fancy about it.
TSD is more involved as it is a fair chunk of code, and my baby. It used to be a separate project from Diulei, but I adopted it and rewrote it, then we moved it into the DT org to give it some officialness (at the time it was a tactical move).
The separate TSD micro-site is a remnant of that, as I described earlier. I kinda like it to have it's own page as it is a separate sub-project not really supported by the whole org (but mostly just me), and the distinctive cyan-on-black style of the CLI interface helps make that clear. But like I said above, we can remove that table and add it to the DT site instead.
What you describe is what we had in mind: searchable index with a bunch of handy links and popovers (NuGet & TSD command, downloads, links to authors, whatever you can make from the data). Basically what is now on TSD's microsite but better.
The redesign of the site will probably take a while, so maybe just move now on a effective but not over-complicated fix for the index :wink:
The big table can be a separate page, and then add a search-bar to the homepage that links there. Details can be a popup or new page, but keep in mind the site is static.
If you're handy with JSON, HTML/CSS and some MVC stuff any work you do is probably mostly valid for the next design. As of now there is no hard plan for an overhaul, it just.. slowly flows. If you want to get involved you can steer it and move it forward just by being active :point_left:.
See also: https://github.com/DefinitelyTyped/definitelytyped.github.io/issues/12 (deeplinks) and the other issues.
If you want to get some talk going on new design and a re-structure make a new issue and ping @diogorodrigues and I pitch in and we'll see who else has something.
Feel free to ask anything. I hope the grunt+docpad setup works for you (it has live-preview etc, see the readme).
Attachment: last preview of the design looked like this:
Hey, thank you for taking your time writing this long answer, just read it multiple times to get everything right.
The layout looks fantastic, I really love the hint to the TypeScript site in the header and @diogorodrigues already changed a lot of things on the front page that feels just right and that the current site strongly needs. Would love to build this thing just now, but I'll guess you guys still have some issues when you write "the redesign of the site will probably take a while".
I'll do as you said, I'll contact @diogorodrigues and start working on the index using your JSON file.
Good luck for tonight :soccer: :wink:
Cool, have fun. If the design pans out you're welcome to build it.
If you manage to find a integration for the typedoc generated documentation then that'd be awesome as well.
For easier updating I think we keep those (and their generator script) in their own repos/gh-pages (well, slimmed down a little from the 1.6GB), but we can easily link them or do other cool stuff.
That repos is here, it looks a bit complicated but that is to have it run 24x multi-core on Travis and auto-deploy it afterwards.
Feel free to ask anything any time.
Oh, apparently the docs generator also dumped some JSON: http://definitelytyped.org/docs/data.json. Could use some improvement but maybe interesting to match files to slugs (and make sure links are good).
@sebastian-lenz I'm trying to get the team to move discussion to this repo. Please [watch] the repos if you want to stay in the loop.
I noticed you got a fork and a test for a docpad plugin. Not sure how that works but keep in mind we'd probably like to be able update the index without rebuilding the whole site. So either some JSON or for static html we could also make a new repos and put the static html in the gh-pages (like /docs or /tsd do now).
Hello!
I could only see this conversation today.
Hey @sebastian-lenz , tips are always great. = D Let us talking about these layouts and define settings?
Hug!
@Bartvds Yes, just did some experiments last days to get warm with DocPad. Creating static pages as targets for deep links / google visibility would be great and also theoretically works with DocPad. But you are right, currently it would require rebuilding the whole thing on changes. As far as I understood it, DocPad would over a solution when run as a server that handles that smarter.
However, we don't actually have that much information in our json file that really requires a separate page to be displayed. Also checked into the GitHub api hoping for some fancy data / statistics to display but had no luck. We could probably display all necessary information with some kind of expandable table / accordion, but this is the point where @diogorodrigues enters the stage...
@diogorodrigues Hey, nice to see you around here. As you may have read somewhere upwards in this thread, I would like to help working on the DT page. As the topic suggests, I started thinking about the package index/search but meanwhile @Bartvds came around the corner with your great layout. So before trying to integrate the search into the current page, we maybe could directly do this hand in hand with the new design and integrate the index smoothly.
So how do you think we could get this thing going? Do you want to keep working on the layouts and we merge everything in the end or should we do a sprint-style workflow? I'm used to build pages from PSD files so maybe I could assist you there. @Bartvds already startet some new issues and got some of the other DT guys to give some comments on the new site, hope I didn't put unnecessary stress on you :wink:
Looking forward to get this thing done together.
Hey @sebastian-lenz ! It is a pleasure to speak with you.
I also think that is interesting to have shortcut to the package. When I started creating layouts, did not have much content. I have Invented some content with the help of the team. Was an initial proposal.
But we can keep improving the interface. The @Bartvds has created this list of topics to be defined, a place where we can speak content: https://github.com/DefinitelyTyped/definitelytyped.github.io/issues/25
Once the content is defined, we can rethink the layouts. = D
I know a little about DocPad. If you need help with this, let me know.
About the tabs, I think that them are interesting. We just need to think of mobile devices as well.
- I will provide the PSDs so you can modify them too.
I think you've already done a great job with reorganizing the homepage, it's more welcoming and really addresses the visitor. And it is great to hear that there is someone around with DocPad knowledge.
I've forked the repository and put together a little demo, you can find it on my GitHub page (unfortunately DocPad seems not to play well with subdirectories): http://sebastian-lenz.github.io/
Very nice demo, collapsible search work very well. Great base to work from for the real thing.
When we go for Live in this approach I have some details and tech stuff, but that's not important for now.
I'll try to get the auto-updated JSON online soonish, besides being updated automatically it has slightly more info too (more authors, multiple project urls and I'll add legacy/release info so we can show we have different node & angular versions.
Details and tech stuff, something terribly wrong?
Great, let me know when you've update the JSON exporter. Just put a library on DT today and stumpled upon the description field. It's not in the header of the definitions, where do you get it from?
For the tech stuff: you've added a bunch of grunt tasks that ideally should be part of the docpad flow: there is a sass plugin; it has built-in watch (+livereload) and it will minify stuff when you (or Travis) build for production (vs development mode as it does locally).
The search bails on some error if you type too soon. "TypeError: a.RepositoryList is not a constructor"
And there is no description.. the element exists but as you noticed there is no source for it. I was going to remove it for the improved json.
My fault, wrong bootstrap order, removed the TypeError.
I can see your point in trying to handle everything with DocPad for the sake of simplicity. But using the content pipeline of DocPad for assets is quite limiting as you cannot use all the wonderful grunt plugins available like grunt-ts and grunt-autoprefixer.
For deployment it should be no problem to add the assets task to the build or deploy task. There is also a plugin docpad-plugin-grunt available for DocPad that runs grunt tasks which could be another option. When running both watchers live reload still works in this setup (using it like this right now) and we could introduce a watch task launching both of them with something like grunt-concurrent.
Let's try to work in the existing thing before we add bypasses and complexity; have you tried https://github.com/docpad/docpad-plugin-sass and https://github.com/docpad/docpad-plugin-autoprefix? And the built in minifier?
That leaves TypeScript, maybe try https://github.com/bpampuch/docpad-plugin-tsc
Okay, I've removed the introduced additional grunt tasks, all runs inside DocPad now. SASS plugin does not reliably run on Windows so I'm working on a virtual machine now and opened an issue (docpad/docpad-plugin-sass#32). The TypeScript plugin is rudimentary so I would prefer to switch to vanilla JavaScript.
Oh, it's more that if there is an existing workflow the first choice should always be to stay inside the existing thing, and only if it really doesn't work out move to the external stuff. If the typescript plugin is too shabby just keep using grunt-ts.
Hello!
It's great to see the work progressing. Now, I have more time to dedicate to the project.
Congratulations @sebastian-lenz , I will recreate the layout in Photoshop creating a new top with search bar and other ideas.
I will ship the fastest.
That's a searchbar :wink: I like it.
Are you happy with the project name next to the logo? Maybe we could safe some space by removing some navigation items (turn "about", "how to use" and "guides" into "docs", remove "repository" from navigation) and put "definitley typed" into one line.
Looks cool.
Question for @borisyankov: is "DefinitelyTyped" one word? Can it be split? I mostly see it being used as one word but could be good to clarify.
Yeah, we shouldn't split it. Most brands that use two words are sticking them together, if the words are shorter the second one becomes lowercase even (Microsoft for example) but Definitelytyped will be a monster-word ;)
@diogorodrigues We should have the logo on one line, possibly bigger font? Don't worry it will become too wide, the menu items on the right should be just 2-3 options (no 'Home' - we'll use the logo, no Blog I guess etc.)
I am pretty happy with the DT box, and am looking forward to replacing the older uglier one everywhere.
@diogorodrigues Can you try a DT variation of the box with lower-case 'dt'. It might look more 'programmer'-ish. Lets do that and we decide on which one of the two version is better so we can replace the logo everywhere.
I love great elements. They can leave the page more attractive. = D
I agree with @borisyankov, I think the the name next to the logo of the brand will strengthen the dissemination of the project.
Sure, you can change the menu links. Feel free. ;)
I'm just not sure about the core content. We'd better define what actually will in that area so we can create something better.
Hug!
We need to define what we really have on the homepage. For me to suggest a new organization of content, improve the icons, maybe insert tabs ...
I will also create a dynamic presentation of the results of the search. I loved what @sebastian-lenz did.
What do you suggest content?
Okay, to get the actual content of the homepage into shape I just fiddled around a little and I have updated my demo. Maybe this is a good starting point for a discussion (can a fork be forked/edited?): http://sebastian-lenz.github.io/
I think the homepage must communicate three import things:
- What is DefinitelyTyped?
- How can I use DefinitelyTyped?
- Motivate users to contribute