Documentation review #1088
Comments
jason0x43
added
domain-documentation
Streamlining the OrganizationI think we have a bit more documentation than we need, or at least the things that users might be interested in are spread out over too many docs. A better top-level organization might be:
Some of the current docs, like Architecture, aren't really applicable to most users. Other sections, like Help, could just be on the front page. If we decide we want human-written API docs, or if we use typedoc to generate markdown docs that are committed to the repo, we can have the API section, as well. |
jason0x43
added
priority-high
Documentation implementaionI personally like having documentation in a readable form in GitHub. It's easy to update as the code is developed, it has a familiar look and feel, and it's easy to maintain as there's no separate build step for it to be usable. Regarding pre-rendering docs on theintern.io, it wouldn't be terribly difficult to adapt the rendering system to output files, or to come up with a different file-rendering pipeline, but I'm not sure if there would be a great benefit to doing so (at least, I haven't heard of any issues with the current system). One minor change that might be worthwhile is switching to Asciidoc. This would provide more built-in high-level formatting constructs, like admonition blocks vs our current use of blockquotes + icons. Asciidocs on GH can also auto-generate tables-of-contents. Doing this would require updating theintern.io to support Asciidoc instead of or in addition to Markdown. API docsRegarding API docs, I think we should try out a markdown solution like https://github.com/tom-grey/typedoc-plugin-markdown. If it's worthwhile, we could drop our current |
The docs were generated with: ``` npx typedoc \ --plugin typedoc-plugin-markdown \ --tsconfig tsconfig-lib.json \ --out tsdocs \ --includeDeclarations \ --excludeExternals \ --excludeNotExported \ --excludePrivate \ --excludeProtected \ --readme none ``` references #1088 [ci skip]
|
Hmmm...no, the generated markdown API docs probably aren't going to work. API docs need more formatting or less boilerplate/metadata to be easily readable. |
|
Here my idea the ideal workflow
This achieves a few things
|
|
Some other notes from reading through the documentation
|
This is something that has gotten easier with GitHub Actions since the last major site redesign. It certainly makes the static site building idea more tempting. We'd need to support doc builds for multiple projects -- the site currently renders docs for multiple Intern projects, so updates to any of them would need to trigger a build, and the build would need to update the doc sets for all of them. That shouldn't be too terrible, though. The in-doc search system would probably need to change, but with a static set of docs we could use something like Algolia's DocSearch, which would have the benefit of looking familiar. |
They actually represent different things -- the links on the top are more global than the links below them. However, I agree that the top links probably aren't very useful (the links themselves, not the idea of having links at the top of the page). |
|
The way that the documentation is organized is very confusing. I have a background in technical documentation (and a degree in a related field even!) so I hope this is helpful:
This belongs in release notes, blog posts, or at most just highlighting a feature is new inline with it's documentation.
This is just obfuscating the content, a quickstart guide at the beginning is helpful, but organize things according to functionality and expose second-level headings in the navigation bar. Try asking some users or friends to do a card sort. I tried doing one, but ran out of time.
Split this (and architecture) off into developer documentation. That can just be .md files stored in the main project.
I'm unable to get this working ATM. Maybe you should have specific information for ES5, ES6 and ESM environments? Finally, cloaking documentation from search results is very bad. I had a hard time finding Intern when doing comparisons on JS testing frameworks. I'm assuming this is part of the reason. |
When v4 came out, we had questions about what new features were available and how to handle updating for quite some time after the initial release. Maybe we should have a "Migration" section that both mentions what's new and provides ways to update?
Showing more second level headings would definitely be good. What level of functionality would be reasonable to break things down at? Intern's current docs organize concepts by functional area (writing tests, configuration, running the testing system). Most of Jest's docs, on the other hand, are in its "Guides" section (like Intern's "How To" section, but with more detail), with many relatively specific subsections. Ava's docs, for another example, also give the "How to" section ("Recipes") more priority. Maybe something more like:
That has been an unfortunate side effect of the current doc system, and we definitely need to fix it. |
I mean, if that's what your users need maybe it is best to put it in the user docs as opposed to a
That example looks much better! When people refer to documentation, they don't want a high-level overview of the software, they are just trying to solve their immediate problem. So they look for keywords related to their problem and jump to that section to see if that solves it (ergo the insane popularity of Stack Overflow). |
|
Closing this since we seem to have discovered the major pain points. |
The goal here is to review Intern's documentation, both how its organized and how it's implemented, and determine how it could be improved.
Current implementation
Intern's documentation is hosted in this repository as markdown files. The README is the front page, providing introductory and getting started information and linking to more detailed documentation. This documentation is also available at https://theintern.io, which simply renders the markdown files from the repo in a custom format.
The site at https://theintern.io can also display API information for Intern. API docs are rendered from an api.json file contained in the repo which is updated whenever intern is built locally (much like a
package-lock.jsonfile is updated whenever a new package is installed). There are no auto-generated API docs available in the repo.The benefit of the current system is reduced maintenance overhead since the docs don't have to be built. The main downsides are that docs on the pretty site may not be indexed by Google, and all doc rendering must occur on the client, which could be slow mobile devices (although I've never heard of this being an issue).
Current organization
As mentioned previously, there are two types of documentation, general docs and API docs. API docs follow the structure of the code itself.
General docs are divided into the following sections:
Questions
A few questions to answer...
The text was updated successfully, but these errors were encountered: