Add browsable index #14
Comments
|
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.
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.
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) 😄 @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 😉 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 👈. See also: #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 ⚽ 😉 |
|
Cool, have fun. If the design pans out you're welcome to build it. If you manage to find a integration for the 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 Hug! |
|
@Bartvds 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 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 😉 Looking forward to get this thing done together. |
|
Hey @sebastian-lenz ! I also think that is interesting to have shortcut to the package. 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: #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 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): |
|
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 For deployment it should be no problem to add the |
|
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. 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. |
|
I made some changes to the layout, what do you think?
|
|
That's a searchbar 😉 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 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! |
|
I was scrolling down after seeing the first image to comment "Focus on the content, give us search directly" but I can see you guys are already there. I actually built my own DT site earlier. I pulled all folders from the github API and rendered them clientside with a search filter for easier access. I like the simplicity of http://www.gitignore.io/ (though improvements on that site could be made) and I think we should strive to keep it simple. Let's remove a lot of the information below "Why use DefinitelyTyped" to a sub page (perhaps make the title a link/button to that subpage) and focus on actual content. But the searchbar and searchresults (already showing 10 of the most popular items) above the github repo buttons. The searchbar and searcresults + index is the most important feature of this site. :) 👍 |
|
@abergs Just a quick note: priority content of the main page is a trifecta of the search (access the goods), the contribution guide (DT is all about contributions) and the Github repos (the heart and guts, with the actual content, issues and PR's). |
|
@diogorodrigues Just to clarify, as I just noted that I didn't literally mentioned it in my post, please take my comments and mocks as my personal opinion and as some inspiration for you, not as a finished proposal. @abergs Great to hear that you the development is useful to you, shows that we are heading in the right direction. I'm totally with you by putting the package search to a prominent place. However, I wouldn't like to hide the other content on a subpage as I think we should explain what DT is e.g. for users that stumble upon our page. @Bartvds Are you happy with the current proposal? Should we put a stronger focus on the contribution section? |
|
I leave the design details to you guys, go for what you think is best. Regarding the structure I'd personally re-arrange the order of the other sections to this:
I wouldn't put [Why DefinitelyTyped] on top because the site is not selling/promoting. It offers access to project and our content. So even though it's good to show why to use DT and not some other way, promoting this choice is not the main thing why the site exists so it should be lower. Maybe at some point we could add a small section on the [TypeScript Directory] but that's for later (the content is a bit stale). |
|
Okay, I'm with you. Didn't want it to be promotion wish-wash, it should give a simple introduction to non TypeScript visitors. I've moved the section to the bottom and changed the text to be more descriptive: The new homepage is in the @diogorodrigues Is this okay for you? Didn't do this in the demo but I hoped we could put your illustrations to the left of the text blocks. |
|
@Bartvds and @sebastian-lenz: I hear you! I just want to influence you into making the process of finding/downloading a typing (which in my mind is the top-% usecase) a main focus. It should be easy to find to upload new typings and I think the layout does a great job introducing new people to DT, but I think we could improve the experience for regulars and powerusers. Let's not hide the content, and instead just have it below the search / index area. One feature I had in my own DT-site was the ability to pull the definition directly into a textarea and autoselect it, making it ready for Ctrl+C, Ctrl+V -- instead of visiting GitHub (which is a pain because you have to find the correct file, click raw etc and then manually select and copypaste). |
|
@abergs Did you note that there is a direct download link in the accordion? Maybe we should make this more prominent? |
|
Sorry, Didn't see it. Perhaps pressing enter(or clicking on the searchresult) could bring up a (small) dialog with a textarea with the definition selected (ready for c/p) as well as link to the file in github and/or a download link which gets you a file? What do you think? |
|
@sebastian-lenz I agree when you say that the search can be great on smaller monitors. I like the effect you did. But I thought to create a responsive site. What do you think? Button on the side with all the libraries to search, I find interesting for reasons of usability. The information is grouped. If the user does not feel the desire to research, he can click the button and go to a page with the search and listing of all libraries. We give two possibilities. @abergs I also like to focus on the main content. Note that the main content is at the top: busca and some highlights to explain what the project is. The rest are additional information. I find it interesting if we lower content for the site becomes responsive for mobiles. How more we can reduce the content better. This makes the focus is on the main content. And sites of a single page or a few pages, are trend. About the download button of the libraries, we can include it directly in the search result. @Bartvds I think its very important tips. We must answer the following: what is, for who she is, and what it is the DT in the homepage This project is something new for me, so I'm leaving you resolve the issue of content while I understand the main focus. |
|
I adjusted the layout:
I think that this hierarchy of content is very interesting because it showed the advantages and then present the tools. First we conquer the users. I also reduce area the tools to take up less space. What do you think?
|
|
@sebastian-lenz I liked the new content structure. But I kept the same amount of content as the more objective better. What do you think? |
|
Wow, this is a big update, especially a lot of details have changed. So this are my personal observations:
You've put the contents of the "Get the definitions" section into tabs right now. I personally would suggest to go with tabs in the "Why use DefinitelyTyped" section and move this one to the bottom. I personally think that hiding the other two ways of getting the definitions is a bit counterproductive: downloading the definitions from GitHub is the most apparent way of retrieving them - so apparent that we actually don't even have to mention it - but we should present and explain the other two possibilities. |
|
After recaping the discussion on this page, I think we will see several iterations of the content till the site is live and probably even after that. There are several good arguments for removing things from the front page changing copy texts or moving parts up and down. @diogorodrigues I liked your layouts right from the start and I think they have greatly improved till now. You've developed a lot of great elements (different colored sections, illustrations, flyout menus, tabs, etc) to work with and I would suggest to move one step further and start building the site. |
|
+1 For just start building: we have enough good stuff to make a fair first version, and it is easier to improve once we see it in action. |
|
@Bartvds Thank you very much!!
Also I think we can start the online website development. And we will adjust with time. You Need that I create HMTL, CSS and JS front-end? I can already do this with reponsivo and then we change to DocPad. |
|
@diogorodrigues I've already prepared the relaunch of the site, you can find an updated version in the branch "relaunch" (https://github.com/DefinitelyTyped/definitelytyped.github.io/tree/relaunch). I would suggest we work on this one. You don't have to build on you own, I'm here to help. I don't know how you would like to distribute the tasks, do you have any preferences? |
|
Sure @Bartvds ! I'm sorry for the way I express myself. We can divide the tasks yes. Let's create a responsive website? It is very important nowadays. I will look this clone with calm and we can find a way to all work together on the front end. But I can also create the HTML and CSS following what @sebastian-lenz did and then you make adjustments and give a force to separate the code in DocPad. In addition to inserting things with JS. What do you think? |
|
@diogorodrigues Just like you want, if you want to implement the template on your own and then integrate it into the current setup we can do so. Bartvds has written a great guide on how to setup a test environment of the DocPad site (just check the readme) so you could also directly edit the final site. This way it would be easier for me and others to assist you. If you want to, you can also drop me a copy of the template and I build the site while you take a look at the remaining issues like the package list or the directory. |
|
Hello! Sure @sebastian-lenz . May be. Let's make responsive, ok? |
|
I will go to publicate the PSD layout. |
|
Everybody wants a responsive site these days 😉 |
|
@diogorodrigues What's up? |
|
Hello!! I'll post the PSD tomorrow. I've been very busy these past few days. Okay So let's do this: you can go by exporting the site and I will create the layouts of the other pages. =D |
|
Link PSD layout: https://drive.google.com/file/d/0B9X-IrgVgEaFRGRZeHFTMVdVTU0/edit?usp=sharing =D |
|
Sorry for the long delay, I was on vacation. Thank you for sharing the PSD, I'll start working on it. |
|
That's a well organized PSD! I've turned the logo into an Illustrator file, is this one okay for you? |
|
Hey, I've updated the demo. What do you think? @diogorodrigues Did you take a look at the edited logo? I've also included a series of PNG right here (dt-logo-*.png). |
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.
The text was updated successfully, but these errors were encountered: