Content structure for new.nodejs.org #19
Comments
|
First draft of how a unified content structure could look like:
|
|
The new taxonomy doesn't have the foundation, is that going to be a sub-site like "foundation.nodejs.org" or just a page? |
|
should we just fold API docs in to the "Resources" page? |
Its placed under "About/Organizational structure" I'm don't know how future content is supposed to look like for the Foundation. We could either give a short explanation of the overall structure and the foundation's tasks and leave the details for a separate
I placed the API docs there at first, but I think most of the people visiting the site will either head for news/downloads or the API docs, so I put them on the main navigation instead. Not sure what's the best way to go there … opinions? It would be nice to have some (rough) log/analytics data from the current nodejs website, to see what parts of the site people are actually reading. @robertkowalski do we have anything in place? Also pinging @nodejs/website for feedback. |
|
@fhemberger yes we have, we also have download statistics for node - @tjfontaine created them using manta probably map-reducing the nginx access logs... |
|
@tjfontaine can you share your manta functions for download stats and other stats? |
Agreed, but I'm not sure it'll help us too much with the placement of API docs since the current website has a "docs" link which them just gives you a link to the API docs. It might be a good idea to do a single docs page with 3 or 4 top level showcase links for API, NodeSchool, and the upcoming documentation the docs WG is building. From there we can see where people are going in terms of analytics and if it's all API we can promote it to top level. Thoughts? |
|
I'll try to take a look at the whole plan soon, but I think it is important to have a "get started with node + nodeschool" pretty front and center and maybe also otherwise accessible. |
Right now those live in the "Resources" page but I'm thinking we can probably find a better name for that section that does a better job of speaking to people who are looking for help. |
I still think that's too obscure. :) |
Do you mean it's too obscure to "find a name for people who are looking for help" or are you just re-iterating my point about the word "Resources" being too obscure? |
|
Sorry, I'm just trying to state that I think it would be good to have a clear "newcomers" section on the main page either way. :) |
@fhemberger I agree, the API should be listed separate in the nav. When I go to a site for a library, the first thing I look for is the API link. I think Docs could be used as a Getting Started guide, with API going to the in-depth docs themselves. (also, sorry about the recent radio silence. Been moving to Pacifica for a few weeks now) |
|
@mikeal @Fishrock123 If you come up with a better name, just go for it. ;) Maybe naming the entire section "Getting started" (and having the ES6 and FAQ pages as sub-menu items) would be a good idea, then place "API docs" right next to it in the main navigation. |
|
FYI: I've started porting the current nodejs.org website to a new, clean structure (including html/css) we can use as a basis for further development. I think I can put up a first draft next week. |
|
Yay miscommunication. @mikeal has really been working on that.. |
|
@mikeal Uhh. Which parts have you been working on so far? I've started setting up a clean HTML/CSS structure which I'm currently testing with the content. Hopefully we merge the stuff so no work has been done for nothing … EDIT: FWIW, this is what I did the last hour:
Basically what's missing is home & download page, the updated content structure and the side navigations for the sub-pages, some style adjustments and cross-browser/mobile testing (including media queries). |
|
@mikeal I've pushed everything I've been working on so far to https://github.com/nodejs/new.nodejs.org/tree/metalsmith-draft. Blog and about sections are working (still with the old content and structure), all blog posts have been converted to use a proper yaml frontmatter section. So most of the work which still needs to be done is review/rewrite of the content. Global metadata can be placed here, localized metadata could be added as |
I'm not so comfortable with this. Far less people are likely to be familiar with metalsmith, and it puts us in an easier mess if segment.io (the sole company which maintains it) moves to anything else, or changes it vastly. I'm also not entirely sure magically covering up what we were doing is a great choice. There is further discussion on build system choice here: nodejs/iojs.org#22 |
To be honest, it was just a test and I really don't care what we're using in the end. I used metalsmith because it gave me the the results for setting this site up very quickly (whereas the gulp tasks could need some improvements here and there). All I really want is to focus on building the site and getting the content ready. |
|
This is much farther along that what I was doing so I'm going to scrap my thing and we can start from here.
Let's not bikeshed about tooling. If this is doing everything (including the internationalization and build/release integration) that iojs.org is doing let's move forward. If people don't like this tool then send a PR that replaces it with gulp or whatever tool you like better and we can discuss the switch that way. |
|
@fhemberger let's merge this to master, nothing is being automatically deployed yet so it's easier to just work out of master while we're still in this early phase. |
|
@mikeal I haven't figured out all i18n aspects yet, but this should give us the opportunity to get started with the english version quickly and adapt to other languages on the way. I'll merge it to master for now. |
|
One benefit I can see to this approach already is the use of yaml in the markdown files for variables and then a main content area makes it much simpler and more readable for localizations. When I was porting the old system the JSON files for localized variables was very tedious. |
|
ok @fhemberger I just made some big changes which make the build system work for localizations. one thing that I had to turn off was the development server support because we're now working with multiple instances of metalsmith so we can't use the build server from any single one. for a dev server we'll need to use a static file server like |
|
@mikeal Just had a brief look at it:
|
Working on this. Moving static is easy but the css has to actually run through the compiler so it's a little trickier. Also, it would be nice if locales could adjust their css on a per locale basis while inheriting the base css.
Can you give an example?
Doesn't work when you're loading static files. However, I have a dev server half working now so this will be changed back soon.
Haha! I don't know why I tend to "tighten" code up like this, I'll try to refrain :) |
|
@fhemberger do you know of a way to get @import in stylus to resolve another path rather than just the current relative path? |
|
I think you can pass additional lookup paths to stylus, haven't tried that yet. |
|
Just figured it out, spent like an hour debugging this esundahl/metalsmith-stylus#14 :) |
|
@fhemberger check out the latest push.
I think it's time to start rebuilding more of the content :) |
|
@mikeal Uh, sorry for the extra effort with stylus. I already forked the plugin to add autoprefixer support, I'll add your PR to it as well. Hopefully both get merged soon. |
|
@fhemberger i worked around it by sending a relative path, so it works now :) |
|
@fhemberger I'm gonna close this issue, since it has gotten quite long, and create a new one with next steps. |
|
FYI this merging without a GitHub PR was very confusing. (I know I'm a little out of the loop, the last few weeks have been hectic.) When tracing back where all the new files came from ... no PR. (Even if one approves their own PR, I guess, it helps keep large changes/additions traceable.) I'm going to do a little playing with this tech stack and see how well it aligns with our goals for i18n, workflow, etc. ... I remember using Metalsmith for something a few years ago but it is vague now ;) |
|
Oh, was also going to say thanks in general for getting the ball rolling on this. My few concerns re: PRs and tech may sound negative, but really the effort to port content is very much appreciated! |
|
You're welcome. And I understand your issue with the missing PR. In this case we went directly from "I have some ideas, so I set them up in a separate branch for you to look at" to "Great, push it to master please". ;) |
|
We will start doing PRs as soon as we're being deployed |
At the moment, the content structure of iojs.org and nodejs.org is very heterogenous, so simply merging the content of both sites for a new.nodejs.org won't work. I took the time and went briefly over the structure, which is currently in place:
Content structure iojs.org
Linking to: Downloads (/dist directory), Weekly Update (external), News Archive (external) and Nightly (next) releases
Relationship node.js/io.js, semver, contributing, open source gouvernance
Description of features and flags
Footer links
Content structure nodejs.org
Including web server example
Download links in platform matrix (32bit / 64bit), external platform support: IBM Power Systems/System Z
General text explaining tutorials, localization and API docs
Short text about NodeSchool, no further resources
Links to international communities and user groups – not about localization/localized content
Introduction text to the three topics below; only focused on node.js core development.
Introduction text to the topics below
Logos of members, separated by platinum, gold, silver status
Links to hand picked articles on blog.nodejs.org, github issues, joyent.com, medium.com, developer.intel.com, …
mixed list: report issues, docs/code contribution, events, mailing list, GitHub issues, IRC, various community sites, official API docs, NodeSchool, Stack Overflow, again links to GitHub, contribution/localization, …
"hello world" http server
Description of patch/minor/major releases and scoping features, not actual list of releases
The text was updated successfully, but these errors were encountered: