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.