Redesigning the Express Documentation

[waleedtariq109]

Redesigning the Express Documentation

[crandmck]

I too agree that the existing docs are outdated and need a LOT of work. FYI @waleedtariq109 I helped create these docs a long time ago, but haven't worked on them substantially for over 6 years, and the other folks on the project have had higher priorities, so the docs have slowly deteriorated. @wesleytodd has helped to reinvigorate the project recently and I'm starting to re-engage as well.

As @wesleytodd noted, the localized content is a huge asset and we need to keep that in mind as we proceed. We don't want to "throw out the baby with the bathwater."

There is the general question of how much effort we should put into 4.x docs vs. 5.x docs, since 5.x is the "way forward" and 4.x is (or will soon be) essentially a legacy version. However, there are still a LOT of 4.x users, and of course we don't want inaccurate docs even for an old/legacy release. IMO we should at least get 4.x docs in better shape before focussing exclusively on 5.x, but this is open to discussion. Clearly, there is lots of work to do on both. There are a large number of open PRs (30+) and issues (60+), some of which have been open for years :-(

Given the huge backlog, we need to triage the work to stand any chance of making progress.

General areas of work include:

• Fixing known errors/problems in the existing (4.x) doc (e.g. open PRs & issues).
• Removing old/irrelevant info in the existing (4.x) doc
• Improving the completeness and accuracy of existing (4.x & 5.x) doc (via new issues/PRs)
• Improving the usability of the doc site
• Documenting new 5.x releases (API doc)
• Writing tasks and tutorials for 5.x
• Improving the tooling/framework used for the doc (Jekyll currently)

There are probably a few more general areas, but these are the ones that spring to mind.

I hope at some point we can set up a documentation team/ working group.
@waleedtariq109 would you be interested in joining it?

cc @expressjs/express-tc

[wesleytodd]

Would it help as we start up the Triage team activity again to ask folks to focus attention on the website? I agree that we should be careful about spending too much time on v4 or v5 until we actually land v5 and even after folks will need a year or so of the v4 (if not forever lol) docs so we should make sure any decision we make dont break those.

[waleedtariq109]

@crandmck Yes, Why not. I'd be happy to join.

[wesleytodd]

Strong agree! I think the main issue for this is how much amazing effort has gone into the translations over the years. Any large change either needs to have folks signing up to help with the language support or re-use the existing content. IMO it would be a big miss to regress on those.

[crandmck]

@waleedtariq109 Thanks for kicking off this discussion!
I'm going to close this issue in favor of #211, which will serve for long-term planning and discussion of Express docs.