Public documentation layout and structuring changes
We've had some recent changes go live on our public documentation site.
Visual / Functional Changes
- The left and right navigation are now fixed and in their own scroll containers (scrolling the document won't lose your position on the edges)
- The right panel, will now appear on smaller screens
- The right panel will no longer contain nested documentation pages. Instead it contains links to all the H2's in the page
##and will smoothly navigate to them when clicked. - The left panel will function how it did a few months ago. (nested docs hidden unless in that section for desktop, everything shown on mobile devices).
Re-organization of the documentation
In order to make space for this new "in-page" navigation, documents nested more than 2 levels deep in the help and developer sections of the site are strongly discouraged.
All existing documents deeper than this have been combined into their parent documents or moved.
Creating new docs content
For the future, when creating new documentation try to do the following:
- Use H2 tags (
##) liberally. More than 10-15 is a bit much, but remember that each h2 becomes a linkable, and easily navigable part of your document. - Extend existing documents where possible instead of creating new pages.
- Avoid giving the first h2 the same name as your document title.
- Avoid creating deeply nested documents.
Example
A few example's that I converted:
- Social connect plugins - These were under the addons heading (in the help section). What is now 1 document was once 6 separate pages, nested like so:
addons->social-plugins->facebook. The document is still easily manageable and something like the facebook section can still be linked to by clicking the little link button next to the facebook title
- Advanced Editor - Additional Settings - The advanced editor previously had a separate page for it's additional settings. They are now simply a heading in the main page. Easily reachable from the right panel.
- JSConnect - The JSConnect docs were previously 5 pages total. They have now been condensed into 2 documents. 1 large detailed page, with numerous sections, and a quickstart guide. If a document is feeling a bit long, try moving it into a parallel document instead of a nested one
Comments
-
Are redirects in place or will there be issues with links to old docs. i.e did urls change for older items? I ask for SEO reasons
1 -
We were careful not to, we added "aliases" (i.e. the way Hugo handles redirects) for all old pages. Adam also made a cool script that compares your changes to the old sitemap for any missing pages.
0 -
@Adrian I wrote a tool to verify that before and after, every single link in the old sitemap is still accessible (either is still a page or is a redirect to a page). As a result I'm quite confident that those links are still valid. At worst there will be 1 additional redirect in the chain.
In cases where pages became subsections I've updated the URL's to also include hashbangs wherever I could find them (so they point to a specific section of the page). During this process some of the existing links to old docs (and some links that redirected through vanilla blog posts) got updated with new links.
0
