Dissect user, dev and deployment docs; add frontpage

[dennisreimann]

This is a draft/proof of concept for how to tackle #501. I've implemented it to provide something we can click through and discuss.

Main changes:

• Split up docs into the user and dev sections
• Put the docs into specific folders per section
• Introduce a custom homepage that links to each section
• Homepage contains a prominent search to find docs across sections
• Navbar links to sections, each section has a separate sidebar

Some screenshots …

Feedback welcome :)

[Eskyee]

Thats looking awesome... @dennisreimann
User Guide ;) nice!

[Eskyee]

Just that small thing has broken up complicated docs, into more fun and searchable docs, thanks Dennis

For noobs, instructing should always be kept very simple!!

For nerds, let them have it, in every detail. Under the hood. 🙏

[pavlenex]

Thanks for the concept Dennis.
I'm still not convinced if this is the way to go.
Search would have to be perfect in order for this to work, right now it's okay, but far from perfection and can't resolve every problem. Then we'd have to hope user would manually choose user doc and go there to find the issue manually.

I need to think about this a bit more, while in theory it sounded okay, I'm unsure if a change like this would cause more people not reading the docs. Don't have any concrete feedback right now unfortunately. Need to gather my thoughts and just think if there's another way to tackle the separation that's not as disruptive.

[britttttk]

@dennisreimann I think it looks awesome!

I think one of the more challenging parts of this change would be to go through and decide what is dev vs. user docs but that distinction has been discussed elsewhere.

Also changing links in the docs/UI is super painful, if that is needed to split the docs.. I guess that is a drawback, but it seems we're wanting to make this change either way.

Overall though, I really like it. @pavlenex I don't see why search would be too much of an issue. That is what we are expecting users to do in FAQ already. I'm also using the overall search quite often as well. I think it should be clear to the user which doc to choose.

if a change like this would cause more people not reading the docs

I disagree :)

[pavlenex]

@britttttk

I don't see why search would be too much of an issue.

Because you exclusively rely on a search to provide a solution to a problem, and if it is not good enough, you expect people to click user-doc and start searching themselves. IMO that's unlikely scenario. The way current search provides results is overwhelming, but people can still read through docs and find solutions because we have a decent sensible structure.

To be clear my argument is not against this layout. I'd just like to take some time to figure out if the initial idea has oversimplified how people interact with documentation.

So I'd like us to figure out a proper fallback way. By the way relying on search means we have to do quite a lot of work on improving wording and adapting our FAQ especially to match exclusive search phrases people use. Not an easy task and would require lots of trial and error, but possible.

Maybe at the bottom of the page (footer) we can provide some sort of structure that can lead user. Any ideas guys?

[Eskyee]

I think there are two things here, how we use the search, keywords and metadata can help this here, and I like how GitHub and these other companies deal with search. which I find very clear.

ask it a question .. u can see the results.. this a good example of search function.

https://help.github.com/en

https://developer.squareup.com/docs

https://docs.blockstream.com/index.html

and the other thing is I like @britttttk said

"I think one of the more challenging parts of this change would be to go through and decide what is dev vs. user docs but that distinction has been discussed elsewhere."

The BTCPay UI interface is quite simple and logical. explaining this should be kept short and simple. because the end user just wants to get going. Noob or Advance.. learn as you go.
the dev docs, has so much more details, coders and developers need to check the workflow and help explain this blah blah blah. etc etc, clarity and information is more important here.
but overall I find the documents to be great, I have used often over years to check and understand what I don't know. but as more features have been added this has grown more complex.
layout is also important to deliver information in a easy to digest way!

I think in time, after the updates, the docs will be awesome.

@dennisreimann @britttttk @pavlenex

[pavlenex]

https://help.github.com/en

This is what I was referring to when I said adding more navigation links in the landing page, below user vs dev docs, as most people may not know what goes where and search may not always provide an answer.

[dennisreimann]

For that we could have a link list or a tailored introduction section on the homepage, where we link to often looked up pages – hence leading the user into the guide where they can explore more.

Again: this isn‘t meant to be perfect in its current form, but I wanted to get us going discussing this further and in a more concrete form. That part of the mission seems accomplished 😀

[britttttk]

https://help.github.com/en
This is what I was referring to when I said adding more navigation links in the landing page

Nice one @Eskyee & @pavlenex that would be really good to have those general buttons on the landing page. I guess we would need to brainstorm what we might want our "main pages to be".

It might be hard though for a topic if both User and Dev have the same section. For example Deployment could be both User and Dev.

But yes I think us relying on the search is also mainly possible because we know what to search for in most cases. Users are gong to be searching things like "doesn't start" and "doesn't connect". I definitely agree our search can't solve problems like that very easily.

[Eskyee]

Product: User documentation
As the name suggests, user documentation is created for product users. However, their categories may also differ. So, you should structure user documentation according to the different user tasks and different levels of their experience. Generally, user documentation is aimed at two large categories:
end-users
system administrators
The documentation created for end-users should explain in the shortest way possible how the software can help solve their problems. Some parts of user documentation, such as tutorials and onboarding, in many large customer-based products are replaced with onboarding training. Nevertheless, there are still complex systems remaining that require documented user guides.
The online form of user documentation requires technical writers to be more imaginative. Online end-user documentation should include the following sections:
FAQs
Video tutorials
Embedded assistance
Support Portals
In order to provide the best service for end-users, you should collect your customer feedback continuously. The wiki system is one of the more useful practices. It helps to maintain the existing documentation. If you use the wiki system you won’t need to export documents to presentable formats and upload them the servers. You can create your wiki pages using a wiki markup language and HTML code.
System administrators’ documents don’t need to provide information about how to operate the software. Usually, administration docs cover installation and updates that help a system administrator with product maintenance. Here are standard system administrators documents:
Functional description — describes the functionalities of the product. Most parts of this document are produced after consultation with a user or an owner.
System admin guide — explains different types of behaviors of the system in different environments and with other systems. It also should provide instructions how to deal with malfunction situations.

I found this interesting @britttttk @pavlenex @dennisreimann

https://blog.prototypr.io/software-documentation-types-and-best-practices-1726ca595c7f

[dennisreimann]

As for the start screen and directly linking to the most important sections: I like how GitHub does it …

[pavlenex]

@dennisreimann Me too. Simple and clear.

[dennisreimann]

@pavlenex Shall I go ahead, rebase the branch and tinker with that or how do we want to proceed here?

[pavlenex]

It's cool concept imo, and I think it's good idea to go ahead, at least so we can visualize how it can look on our end. Maybe no need to rush merging it in, since in a way it's a big navigational change for people.

[Zaxounette]

As for the start screen and directly linking to the most important sections: I like how GitHub does it …

I love how they did it.
IMHO it's the best FAQ/Docs that we could get inspired by.
Clear, concise, and the info is generally easily find-able.

[dennisreimann]

I've updated the branch and reworked the structure a bit. To not loose SEO juice and keep the old links working, the users guide now stays at the root of the site, instead of living inside the guide directory. Way better and makes rebasing with master easier.

Also the development section now has a better structure.

Next I played around a bit and would like to hear your thoughts on also extracting the Deployment section. It is a big part of the docs and setup/maintenance to me feels like a whole topic in itself. That's why I've come up with the following …

Home

---

Section

This section is linked to in the header and also has a navbar on its own …

---

Guide Navbar

Extracting the Deployment section imho gives a more interesting flow from the users perspective in the guide then …

---

Haven't pushed this yet, but would invite feedback and am curious to know your thoughts.

[Eskyee]

nice work, love the layout design, and the idea of reducing information overload, with the sections.
I also think scale down the supporters logos, as it dominates the page, at this size,
love the search field in front, nice & easy. UI UX. bammmm.

the Guide Navbar flow is important, nice touch.

a great update, & attention to detail. makes you think much faster and clear on the direction to take. @dennisreimann

[Eskyee]

maybe I would try & greyscale the logos as a second idea. might give us a cleaner looking page. @dennisreimann

[Zaxounette]

I really like the User Guide(s) <> Deployment <> Development on the home page.

It looks neat and the differentiation is, IMHO enough for anyone to understand what they are likely to find in the corresponding docs.

Also, a bit of feedback on the header menu: Guide should be User Guide for clarity, but most importantly consistency between pages.
Also, it's User Guide, not User's Guide or Users Guide. Semantics :)

Finally, a personnel though: Would it be worth-while to differentiate FAQ's as well ?

[pavlenex]

I'm not sure I'm 100% for this until our search preforms better. I like the layout but I think it won't provide best experience for someone searching for an answer. The current docs have structure and links, so even if search lets you down, you can navigate up and down to find a link that may helpful. Current layout looks great but I'm afraid people will get lost as they land on the page. We either need more links after the main 3 CTA's or improve our search results. With this sort of layout we're hoping user arrives to this page, gets a reply in search (which is imo quite unlikely the way our search now looks) or knows the difference between deployment, user etc. Every user needs deployment there's no way to bypass it, hence separating deployment is confusing imo.

I think this is a good starting point, but needs more eyes on this and actual tests. Also if I may suggest, I don't think it's good idea to merge this until our dev docs are fully complete, right now dissecting docs without having proper dev docs makes no sense to me.

Perhaps if within the box we provide a CTA with links to sub-sections, it can be a good compromise. Example. This example also provides how sidebar can help in landing page navigation. It doesn't look clean, but imo it provides better navigation.

Just some feedback for brainstorming, I am not against this, just think it needs UX people to look at it as well as actual users who're looking for particular info. Remember docs are there to help people and reduce support on our end, and if people come to chat asking where to find stuff in docs, then we failed.

[Eskyee]

ok yes its good to brainstorm this, as for now look from a google search user as a example.

I think the art to good design UX & learning, is to give the user what they need at that moment. and not overload the user to think more than needed to complete their task or find a solution..
I'm sure the Search can be improved with metadata, to the right documents and information needed,
adding to many links on the docs landing page, is just adding screen clutter. the idea here is to present information you need at that moment in the most simple friendly way,
once a user has deployed, btcpay server he won't need to read those docs again, most new user after deployed will spend their time in user guide, and developers will spend their time in development. need help fast they can check FAQ or search bar.

I don't think people will get lost arriving to documents when it becomes logical and Instinctive.. that's great design.. no need to ask support! unless reporting a bug!
it good to talk from a user idea.. and get lots of feedback, maybe a twitter poll ?? Pav
no rush to merge, but how we deliver information in a clear sharp simple way. Layout.. Design.. Detail..
documents are flowing much better now with the updates happening. nice work!!

What is simplicity in design?
Simplicity is the discipline of minimizing, refining or editing back a design. The ultimate goal of any piece of graphic design is to make an impression. ... We consider simplicity to ensure that a piece of communication has maximum clarity. We consider simplicity to create balance and impact.
I think this is the same for simplicity in the information we give and how we teach to use those tools. for everyday use.
Don’t feel we have to over-simplify everything - some products don’t need to be simple. Instead, we focus on making them as enjoyable for the user as possible.

great information !!

rule 101 of UX but as a refresher, make sure we know who are users are, how they will be using the product and what they are trying to achieve so we can work out how best to simplify the product to their needs.

Simple is complex to get right and it will take time and many iterations. Keep referring back to initial research to make sure we haven’t gone off- piste and use user research to make sure the original idea has not been lost through over-simplification.

[Eskyee]

Microsoft search function is powerful and works fine, as a example in documentation they use metadata search. .. https://docs.microsoft.com/en-gb/visualstudio/?view=vs-2019

Also adding this to our documents if a search term doesn’t provide a answer..

Ask a human

Can't find what you're looking for?

Contact us

[dennisreimann]

I'm not sure I'm 100% for this until our search preforms better. I like the layout but I think it won't provide best experience for someone searching for an answer. The current docs have structure and links, so even if search lets you down, you can navigate up and down to find a link that may helpful.

There are two things I'm struggling with in regards to this:

• Even though search is front and center and we maybe can dim its appearance a bit, it is not the only option on that page and the sections provide a clear distinction on what to expect and find in each.
• For the search to be refined, we need clear goals or at least define what exactly the current problems are. Without that we are stuck here.

One thing that is still missing too is the part I refered to with this comment, in which we highlight the most looked for topics and make them also directly accessible on the homepage. Those would need to be defined and I wanted to discuss the additional deployment section first, because it feels relevant for this part too.

However, I'll let this rest for now until we've gathered more feedback and can decide on an approach to finish this up.

[britttttk]

Search

we need clear goals or at least define what exactly the current problems are

Agree, perhaps we should create a separate discussion issue

Landing page

I really like the User Guide <> Deployment <> Development on the home page.

Agree, it should be User Guide

Would it be worth-while to differentiate FAQ's as well ?

I think we should create a developer FAQ regardless :) but I am open to the way @Zaxounette has suggested it in the landing page.

Deployment as a Main Section

It is a big part of the docs @dennisreimann
Every user needs deployment there's no way to bypass it, hence separating deployment is confusing imo. @pavlenex
Once a user has deployed, btcpay server he won't need to read those docs again @Eskyee

I would say deployment is the biggest barrier to entry for anyone wanting to use this software. As it has been pointed out everyone needs to do it. I agree, and this is why imo it should be prominently displayed. I also fully agree with Esky's comment that these docs will also be largely completely avoided after they have deployed. The exception is FAQ, which honestly most of the deployment maintenance FAQ questions should be in the dev section anyways...

Docs UX

I agree with Esky, we should try to not expose all things to the user.. but try to help them discover what they are looking for. I think by now we have all looked at several websites and have discovered Github docs are very clean looking compared to others, and the reason is because it abstracts away most unnecessary info.

A good example is Pull Payments docs. This is very likely to be more in the "power users" realm of btcpay (at least for now). Create a store and invoices is more for say, beginner users. So how can we help users have a good docs experience based on their use case and user level? We have already partitioned the docs into user stories, but what about user level?

Deployment (1), User Guide (2), Development (3) seem to me good ways of doing a "user level" concept.

Example 1 or main docs page

• This is a fairly complicated software tool that looks very simple from the docs page because so much info is abstracted away, mostly in the nav bar and the home page.
• Not as pretty, but the simplicity feels like something a user could take in and navigate without being overwhelmed.

Example 2

• "Organized" and looks modern but too much information is presented to the user. I think that is similar to the microsoft docs example but instead of links we have cards.

Example 3

• The user probably goes first to Getting Started > Register Account > Sees Third Party link?? > etc
• There are questions in the chat of users wondering about registering on mainnet.demo probably from TryItOut.md doc so some users are getting a bit stuck there i think as well.
• I think we are not providing a good idea to the user of the steps still.. as @dennisreimann mentioned, improving the flow.
• I think deployment should be like READ THIS FIRST otherwise you are not technically a USER yet so don't even bother with USER GUIDE unless you want read concept stuff...

[pavlenex]

Users don't need docs to discover stuff, this is not a RPG game, they want answers to their questions quick. If there's no clear navigation, I don't see how we can expect users to know where to find their answers, especially because the search provides so many confusing results at once in most cases.

I suggest we keep the sidebar for navigation and mix that with what you guys suggested already for the front page.

I also suggest you guys to take note on how often do you find yourself using search vs using navigation on the left. For me search provides so man irrelevant results that in 90% of cases I use the navigation in the sidebar to find my answer. I can only imagine how it's for newbs. I definitely would not rush with this one until we get more user feedback.

[dennisreimann]

If there's no clear navigation, I don't see how we can expect users to know where to find their answers,

I get this, but on the other hand the current sidebar contains all topics at once. This also provides no guidance, which we could accomplish by separating the individual sections (each of the having their on sidebar). My point here is not to say is above is perfect, but to highlight that the current navigation might also be confusing as it overwhelms with this all-in-one approach.

especially because the search provides so many confusing results at once in most cases.

Agreed, so let's go ahead, define what we want and see how we can tweak the Algolia settings – maybe there are some low hanging fruits there like not providing 25 results …

[Eskyee]

😂 RPG game .. that’s a good one ☝️

Humans can hold only four or five items in their conscious awareness, or working memory, at one time. Overloading that capacity causes the neurological juggling act behind working memory to fall apart.

Discovery is how we understand life. And how we store that memory. 🤓🧐

[dennisreimann]

Ok, I refined this a bit, incorporating all of the feedback – thanks for taking the time to elaborate on your points!

The "Explore by topic" links are exemplary – we can define what we want to have there in further discussion.

Light

---

Dark

[pavlenex]

@dennisreimann Great! I'd probably add more section to explore by topic and make supporters logos in 1 row, smaller and less visible, there's no need to display them as prominnelty so it distracts from docs usability imo.

[dennisreimann]

Ok, here we go…

[Eskyee]

Nice work 🙌

[Zaxounette]

Nice <3

What about the FAQ (single or multiple) section ?

[dennisreimann]

What about the FAQ (single or multiple) section ?

I'd keep the FAQs associated with the individual sections. For more it makes most sense this way, but let's discuss this too.

[Zaxounette]

I'd keep the FAQs associated with the individual sections.

Well multiple FAQ sections then 😄

Seriously, I was referring to my "screenshot" and Pav's mockup, both containing sections pointing to a FAQ, or multiple FAQ"s directly in the home page.

Also, semantics question here: Why call each section a guide ? Why not just call them docs ? (As in User Docs / Deployment Docs / Developer Docs)
Especially if the FAQ's for each section are included into them and not separate.

[pavlenex]

Why call each section a guide ? Why not just call them docs ? (As in User Docs / Deployment Docs / Developer Docs)

I agree with this one.

[dennisreimann]

Why call each section a guide ? Why not just call them docs ?

Ok, will fix this once we are near finishing this one :)

[dennisreimann]

Updated the branch and incorporated the feedback. Also taking it out of draft mode, because everything is basically here.

One thing we haven't discussed and might want to change ist the list of topis on the frontpage. Just let me know what should be featured there and I'll update the list as well.

I don't want to be pushy with this, but from what I see we can't go on from here with assumptions. We could ship it, see what people think, gather feedback and improve it from there.

[pavlenex]

IMO this change will make sense once our docs are good enough. Differentiating docs when our dev docs and search on which we want to really on are really bad makes no sense to me at this point in time. So, personally I'd hold this on until we analyze and adjust content that will lead to better search result and when we have a proper dev docs.

I think people need to test this locally and not provide feedback based on the image. I've been testing it regularly and I juts don't think it's an improvement in terms of usability the way it is now. This is not the question of your design or code, it's more like we need to do a bunch of improvements in docs so that structure like this makes sense.

[Zaxounette]

Okay, so to summarize (and to dumb down for my brain), the identified goals that you stated Pav are the following:

1. Search engine tweaking ( Tweaking the Algolia search engine #628 )
2. Analyse and adjust current docs to fit better search results (ie. add keywords SEO/meta'like to titles) ( Tweaking the Algolia search engine #628 )
3. Have proper developer/development docs ( Developers documentation #174, Drawing a line between user documentation, dev docs and advanced? #501 )
4. Improvements on the docs

Could 4 be clarified ?

• What to you have in mind for "a bunch of improvements in docs" ?
  Would a complete re-structure of the docs to clarify user docs (learn to click on the UI) and dev/advanced docs be part of that improvement ? (Drawing a line between user documentation, dev docs and advanced? #501 (comment))

[pavlenex]

@Zaxounette

What to you have in mind for "a bunch of improvements in docs" ?

Basically the bullet points you already outlined quite well. But on top of that, we'd have to have keywords in titles that people are asking, which is related to bullet point 2.

[Zaxounette]

Basically the bullet points you already outlined quite well. But on top of that, we'd have to have keywords in titles that people are asking, which is related to bullet point 2.

Thanks :)
Edited the bullet-point comment just above.