Aerial View Of Athens Documentation

[marwan-at-work]

Our docs website is not well organized as of right now. I still struggle to find things I wrote myself because I'm not sure which section it belongs to.

We should holistically look at how to make our documentation an end-to-end journey. Something simple, understandable, and just great...I know I'm throwing jargon here, but I believe it's really worth it.

So before we just "code something", we should think about the experience itself. How should the experience of our docs website look like?

Questions to be answered:

1. Should we make our docs just one single page, with a navigator on the side?
2. What should the sections look like?
3. Can we make sure that everything is documented on the website and no one needs to go to github for external documentation (such as the config.toml file)

[marpio]

I think it's a good idea to think this through - maybe we could make a small list of projects with great docs + some description of what makes it so good. Something like:

• Project A - I like it because X and Y

We could then compile a list of features we think are important with examples.

[ghost]

We should do the same for #922

[arschles]

We should probably include the reference from #921 into our new docs setup too

[arschles]

@marwan-at-work thank you for opening this 💯 🎉 I put my opinions on your questions below

Should we make our docs just one single page, with a navigator on the side? What should the sections look like?

I feel like we should have these:

• Intro: the "elevator pitch", background on modules and more details on why Athens is rad, and a quick start
  • I think the quick start should be the focal point, and I also think this is where the single page with navigator would look great
• Community: non-technical stuff, like what we already have in https://docs.gomods.io/contributing/, but maybe better organized
• Advanced: everything you'd need to deploy an Athens inside your company (i.e. stuff from https://docs.gomods.io/design/), and reference documentation like explaining everything in config.toml like what you brought up

Can we make sure that everything is documented on the website and no one needs to go to github for external documentation (such as the config.toml file)

• :100: here. We already do a pretty good job of making sure docs get updated in PRs too, so we'll just have to make sure the docs site gets updated.

Let me know what you think?

[arschles]

@marpio here are some projects that have docs that stand out to me:

• Buffalo has these things I like:
  • The top of the home page has a one-sentence description of the project and a getting started button
    • The "main features" grid on the home page gives me an idea of what exactly I'm gonna get, beyond the one-sentence
  • The header looks nice 😄 and has simple links to each section. I feel like wherever I go I can get anywhere else
  • It has build badges at the bottom of the home page
• Hugo has these things I like:
  • It has that one sentence thing that buffalo has, and then another smaller sentence that elaborates
  • It also has a header like buffalo, and includes the twitter and github star icon
  • The quick start button is prominent
  • The docs section has the sidebar with high-level topics that expand so you can navigate to details on anything really quickly
• Gobot has these things I like:
  • The same title + value proposition the other two have
  • Really colorful home page
  • Github (star and fork) and Twitter (tweet and follow) buttons right on the home page
  • An immediate code sample
  • instructional videos
  • The docs are easily navigable like Hugo's

[arschles]

In the Dec 6 meeting, @manugupt1 suggested that we should try un-collapsing the sidebar of our site and seeing how much further that takes us

[arschles]

I obviously have #972 open, but I am also going to create a draft sitemap. I'll share a link to it in here when it's done