Create new Express website

[dougwilson]

I'm opening this issue for discussion to create a new Express website for information and documentation for our awesome project. The goal is to create a website that lives under the Express TC and the Node.js foundation. We can easily create the site using GitHub Pages, probably just under http://expressjs.github.io

[dougwilson]

StrongLoop/IBM contributed back the main Express 4.x documentation (currently at https://github.com/expressjs/express-api-docs) and the 3.x and 2.x documentation was created by TJ, so this could easily be used as the initial content for the website.

Adding Express TC governance information, members, etc. would be an easy next addition. The meeting notes, links to recorded hangouts, and all kinds of things could be there after that! It sounds really sweet.

[sjanuary]

I'm not sure if I've missed a back-story behind this issue, but how will this relate to the current website at expressjs.com. Is it a different intended audience or is it being proposed as a replacement?

[dougwilson]

Hi @sjanuary, the proposal here is a replacement or something. The Express.js TC does not have a way currently to influence the website besides just acting as external contributors (see expressjs/expressjs.com#580 (comment) as an issue for how hard it is to be an external contributor currently).

I made a proposal to actually get governance added to the website (expressjs/expressjs.com#565) just as we are working to add governance here, but the issue has no comments from the repository owners and seems to just be ignored, so just as Express.js is setup in the Node.js foundation to get a good governance structure setup, including transparency, it doesn't seem like our own website is following suit, which makes it unknown how to best coordinate with the owners of that repository.

There are no members from the expressjs.com website repository in the Express TC and none have expressed interest in even attending the community hangout at #2885

Another problem is that the domain name expressjs.com is not owned or administered by anyone in the Express TC or Node.js foundation, so relying on that domain pointing to what is expected is hard to rely on, especially without documented transparency from that repository and any way for our TC or contributors to join in the collaboration and provide objections/feedback except as outside contributors.

Our Node.js top-level project incubation request lists "Currently there are no IP assets included." under the "Intellectual Property and Other Assets" section (https://github.com/nodejs/TSC/blob/master/Applications/Express.md#intellectual-property-and-other-assets) and the project application guidelines list "domain names" as specifically part of this section (https://github.com/nodejs/TSC/blob/master/Project-Lifecycle.md#applying-to-join), so as far as I can tell, there are no plans to move the existing website under the Node.js foundation, so this proposal is to get started on the due-diligence required in order to ever graduate from incubation. You can find several points in nodejs/TSC#39 regarding the importance the website is to the Express project as a whole, including confirmation that the website is not included in the current Express Node.js top-level project.

Part of a suggestion for the issue that the expressjs.com website is not part of the Express Node.js top-level project is to get the main contents of the website contributed to the Express.js project, which just recently happened. This is just an extension of that, to prove a way to actually present that documentation in a meaningful way, rather than it just sitting around in a directory somewhere. Because the idea of surfacing the documentation within this repository has Markdown documents GitHub can render was nixed in #2892 as "scope creep", instead the documentation was formed into a mini website in https://github.com/expressjs/express-api-docs and now just needs to get exposed as a website, and get that going so people will start contributing changes to this website, which can be synced to expressjs.com by those contributors.

These are just the issues I see, and creating our own, new website is just one possible solution. If it even looked like the expressjs.com repository was going to move towards open governance with us, I wouldn't have opened this issue, but my proposal to that repository has been open for 26 days without comment, but the repository has otherwise been fairly active.

[sjanuary]

Thanks for clarifying @dougwilson.

[crandmck]

(see expressjs/expressjs.com#580 (comment) as an issue for how hard it is to be an external contributor currently).

Maybe I'm misunderstanding, but I don't think it's any harder to be a contributor to the docs than it is to the code. You can see in the repo that there have been and continue to be LOTS of contributions from the community. That particular comment was just about my desire to be able to make small editorial changes to some lengthy contributions. But that's probably just my lack of sophistication with Git rather than anything else. I think what it really means is that I need to learn how to use the (standard) workflow that's been used in the express repo.

There are no members from the expressjs.com website repository in the Express TC and none have expressed interest in even attending the community hangout at #2885

I'd be happy to start attending if it would be helpful. Sorry I didn't weigh in, but I got busy with other projects and lost track of that issue. My bad.

Part of a suggestion for the issue that the expressjs.com website is not part of the Express Node.js top-level project is to get the main contents of the website contributed to the Express.js project, which just recently happened. This is just an extension of that, to prove a way to actually present that documentation in a meaningful way, rather than it just sitting around in a directory somewhere.

You are quite right about it "just sitting around in a directory somewhere." I totally agree that that serves no real purpose as-is. Sorry I kind of dropped the ball over the last week since we copied the API docs to the new repo.

I've been thinking about how to integrate the two repos, and here is what I propose:

• Create a GitHub Pages site from the API docs at https://github.com/expressjs/express-api-docs, which would be at http://expressjs.github.io/express-api-docs (or whatever). This site would contain the API doc content but also have the navigation to the rest of the documentation, linking out to http://expressjs.com for the other non-API docs. This wouldn't be hard.
• Remove the source of the API docs from https://github.com/strongloop/expressjs.com and change the navigation header so that the links to the API docs point to http://expressjs.github.io/express-api-docs. That is, when someone clicks on the API > 4.x menu link, http://expressjs.github.io/express-api-docs would actually load.

The end result would be something that appears exactly like the current http://expressjs.com/ but where the API docs are sourced and published from https://github.com/expressjs/express-api-docs. The site would look essentially the same at http://expressjs.github.io/express-api-docs), although it would have a different home page, I presume.

I don't think it serves the community to bifurcate the documentation into two separate and distinct sites. I think this would be the best of both worlds, with the API docs living under the expressjs org and the remainder living where they are, but being published "together" as it were.

If it would be helpful, I can open a PR in express-api-docs to show what I'm thinking of.

[dougwilson]

Thanks for the response @crandmck, but you missed a lot of the main points, mainly I don't think Express should be linking to a third-party website and the main documentation and website for the Express.js project. We need a website that is under the Node.js foundation governance and instruction, as well as a central location to provide the governance documentation and resources for all the projects that are under the Express TC without copying files into every single repository. We need something like https://nodejs.org/en/foundation/ and other sections of the Node.js website for Express and I don't see how a third-party website can provide this to the community of Express and is completely overseen by the Express TC.

TL;DR I think the Express project needs to get a website overseen by the Express TC setup and stop using a third-party website as the critical community resource.

[crandmck]

@dougwilson I hear what you are saying, and I do understand your point. I'm not in a position to weigh in on that matter, so I'll leave it to you and others to hash it out. I just want to keep doing what I've been doing to maintain and improve the Express docs. I'll leave the high-level governance decisions to you and others.

In the meantime, can I move forward with my proposal above? This will enable us to eliminate the redundancy of the API docs--they currently exist in two places, and we're getting PRs in the expressjs.com repo, which we'll need to copy over to express-api-docs (no big deal so far, since the PRs have been pretty small, but we shouldn't let the two diverge too far IMO).

Regardless of the decision about where the docs live, the doc site, etc, then the doc source will be in a cleaner state, and will be easier to work with moving forward. What do you think?

[dougwilson]

Hi @crandmck, all of this including your, is only proposal; I would not recommend moving forward until there is a decision made to figure out what to be done, and your proposal will definitely be included in the discussion. This is marked etc-agenda and the TC meeting was canceled this past Wednesday, so it will need to wait until after the next TC meeting happens.

[jasnell]

A express project site definitely makes sense and having something at expressjs.github.io for now makes the most sense in the near term. We can iterate on what exact content is there.

@crandmck ... having the http://expressjs.github.com/express-api-docs site and having expressjs.com simply link over to that makes a ton of sense. Personally I'd say go for it. Incremental steps are good. I'll leave that to you tho. As @dougwilson indicates, it's on the agenda for next Tuesday's TC call.

And, to be certain, the discussion around the expressjs.com domain is still ongoing and definitely not settled yet. I'm still having the internal discussion on that albeit it's been delayed as we've all been quite distracted getting ready for the conference this week (the timing on that definitely wasn't ideal). I'll be having some follow up conversations next week now that the calendars are actually clear and will hopefully have another update soon.

In the interim, I've personally registered the expressjs.info domain (unfortunately expressjs.io was unavailable). I'm happy to transfer ownership of that to the foundation (/cc @mikeal). We can use it as a more permanent location rather than relying directly on the expressjs.github.io links (which can be a bit brittle if we decide to restructure things later).

[dougwilson]

I mean, for the time being, we just have the expressjs.com website, and I think, though we have the docs dump in a repo, it's actually good that it is not yet exposed as an actual website since we don't have a fleshed out plan. The initial proposal for that dump was that the two places would be synced with a script, no? Is there a problem with syncing the current pull requests that are arriving to expressjs.com to the api repo?

[jasnell]

PRs can be sync'd. I think @crandmck is just trying to find a way of streamlining the process as much as possible. We had a similar type of issue when node.js was moved from the joyent/node repo to nodejs/node. There are existing PRs that had to be manually migrated over. It was a bit of a pain but eventually settled out. The issues here ought to be temporary.

I think for the time being having this additional site to put the basic API, governance and foundation information makes a ton of sense. Once the question over expressjs.com finally settles out, we can work on coalescing things. Any objections to using expressjs.info in the interim? (I just want to avoid using expressjs.github.io/* if we know that will likely be changing as things evolve)

[crandmck]

Yes, I do want to streamline as much as possible. It would be great if we can avoid having to run a "sync srcipt" every time there's an update to the API docs. I would like to give my proposal a try as an interim solution, so I'll try to carve out some time if I can. I'm actually swamped with other work, so it may be a moot point anyway, esp. since the TC is meeting fairly soon.

[jonathanong]

aside: i'd love for http://expressjs.github.io/badgeboard/ to be part of the new website :)

[Knighton910]

+1

[hacksparrow]

@dougwilson do we want to keep this open?

[dougwilson]

Let's get the ideas expressed in here dispersed as issues in the website repository and then close this issue. I don't want to loose some of the ideas here, which seem pretty good.

[crandmck]

I opened a new issue to clarify contributions & governance of the expressjs.com repo/site (which is touched upon in above discussion): expressjs/expressjs.com#632

There was already an issue for the suggestion to add badgeboard - see expressjs/expressjs.com#285.

The rest of the discussion seems to be around having API docs in a separate repo from the other docs, which is no longer an issue.

@dougwilson Please let me know if there anything else discussed above that you think deserve an issue. Otherwise, I believe this can be closed.

[dougwilson]

Thanks, @crandmck! I read expressjs/expressjs.com#632 and it doesn't sound like what was suggested here, which was to actually put the information on the website, not just in a file in the web site repository (unless I'm misreading that issue?).

[crandmck]

Yes, that was an oversight on my point (I didn't read the comments in that issue closely enough).

I added an additional comment to capture the general idea in an additional comment. @dougwilson Please change or add to that as needed.

Then, perhaps we can close this issue...?

[crandmck]

@dougwilson I'm going to go ahead and close this issue, as I think everything has been captured in other issues. Re the governance/contribution stuff, please comment on expressjs/expressjs.com#632 if I missed anything else on that front.

[dougwilson]

Thanks @crandmck, looks good to me.