Hey everyone,
We’re always looking for ways to make CircleCI docs better. In fact, you may have read that we recently open-sourced docs, which we’re very excited about since it allows us to more quickly create new docs and more easily update our current docs. Our next step is to improve how the docs site is structured, and to that end we’re looking for your input.
Specifically: when you go to our docs section, what do you expect to see? How would you like to most easily find what you need? What’s the best intuitive hierarchy for you to find what you’re looking for?
We’d love to know your feedback on these questions and any other docs-related things you’re thinking about. Are languages best at the top level for you? Do you use the search bar when you’d rather be drilling down into a menu? We’ll be updating our docs early and often, and want to make sure they’re organized in the best way for the most people possible.
Post your thoughts and ideas here. We’re looking forward to reading them.
5 Likes
I’m an atypical developer, so this might be an atypical answer.
For me, I find myself frequently referring to the Test Metadata section as it seems sometimes getting that to work out of the gate can be tricky.
circleci.yml file configuration is another one I use often.
Both of these (and likely several other long pages) could really use a table of contents. There are automatic anchors, but that only helps with direct linking. I’ve always been told that web design rules state to keep scrolling as low as possible.
The search has always felt a little strange, if there was any way to show snippets in the results drop-down it would aid in knowing which result to click.
Finally, if you have these metrics, I would check both the page view count and search keyword count metrics to try and determine most popular (and desired) pages, and factor that data into any redesign concepts.
Hope this helps! 
4 Likes
This might be a little bit late, but I’ll still drop my opinion here.
Sidebar / Navigation
Current Situation
The sidebar shows a list way to long for my brain, so I completely ignore it as it’s useless and a waste of time to search through it.
Recommendation
The sidebar should show a hierarchy of the current page I’m reading on. So please show all the parent and greatparents and so on of the current page). I’d also like to see all other pages that are in the same hierarchy level as the current topic, as they might be related. This would be a good way to find more information in the same section as the current page. All other pages that are not (yet) relevant to me, shouldn’t shown, their parents however should be. (e.g. if I’m reading the page about “background processes” I don’t care for “troubleshooting in Haskell”, but seeing that there’s some “Troubleshooting” section would still be nice, because I might need that in the future?).
I’d also like to see the search in the sidebar, as this would be a good place to show results. This is strongly a personal preference as I generally don’t trust other searches than my main search provider.
Content
Current
The content is more or less good structured. Search bar is not doing what I expect, as the position implies it’s for searching through the current page but it’s actually a global search. (and who was so insane to show all search results?!) “Help make this document better” is really annoying and way to big.
Recommendation
Kill the search field. It doesn’t search the content of the page, so don’t tie it to the content. This is misleading and it doesn’t help my trust issues with searches at all. Also I’d like to see a table of content at the top of the page. This would help a lot to navigate through long pages like Configuring CircleCI. Please make this “Help make this document better” footer smaller. A simple “Improve this site: (Open Issue) (Suggest Edit) (View on GitHub)” should be sufficient. The license footer is too big as well, a simple hyperlink to the license should be a improvement.
Mockup
3 Likes
The suggestions by @einfallstoll and @drazisil are both great, in particular the mentions of a need for table of contents on a few pages, cleaning up the sidebar, and fixing or removing the horrible search.
Would love to know when the docs will get some more love seeing as how the OP is from early this year.
