Why do you think it’s too many? These pages are created once and we’ll have like 2 or 3 per topic average. And we’ll have a Sheet for landing page so all you need to do is create the page from a template, it takes 5s to create one (and more time if you want to add highlights, and related pages but that’s additional value and it could be optional for landing pages for topics).
IMO it’s not a good enough argument for choosing option 3 over option 1. You need to think from a reader’s POV and what’s best for them! (I’m not saying option 1 is better for readers, I’m not sure about it, but I tend to think it is better). If you want to go with the easiest for the doc writers, then you should pick option 2
Maybe what we can do is to make the type pages in the nav tree not-clickable. As a reader, I can already filter by type in the LD of the topic page, so for me the type level doesn’t add much value.
We can still keep the type in the nav tree just to organize the pages under it, but visually show it in a different way, so readers don’t expect to click. This would avoid creating extra landing pages that are not really needed.
WDYT? Thanks!
I wasn’t really thinking about what’s easiest for doc writers. For me, the type landing page itself feels redundant (I’d even call it a duplicate of the topic landing page, just showing less information).
That’s because you don’t value that much the navigation by type (hence your preference for option 3). The top level type entries in the nav are not about navigation (you don’t navigate with them), they just land you another page that you need to use to navigate (using the LD and the filtering). This is very similar in idea to option 2 (where LDs are used fully to navigate). With option 3, LDs are still used to navigate a bit. Less than in option 2 and more than in option 1.
PS: I repeat that I’m not sure what’s best for readers, between option 1 and option 3, but I don’t really like to put all types of documentation pages together at the same level for a given topic, as it mixes it all together and users can’t see what’s an explanation from a howto for example (other than deducing it from the title but that’s not ideal IMO), and that makes it harder for readers to pick pages IMO.
I don’t have a strong preference between options 1 and 3. At a glance option 3 looks nicer since there’s less. However, when thinking about actual use cases, having a quick way to select a combination of Topic+Type from the navigation panel is really useful.
Option 1 would be the best for me, but option 3 is nearly as good and probably a bit less confusing for newer users
The final round is between option 1 and option 3, so for now you’ll find only these two on the new location Documentation. You still have some time left to test both options. @MichaelHamann, @mflorea your feedback would also be very valuable if you’d like to share it. Thanks!
I think I prefer either version 1 or 3. If each (available) type of documentation covers the whole feature, I think option 1 is best as this allows me as a reader to choose if I either want to read the reference or a more how-to/tutorial-style documentation. If I need to read pages from different types to cover all (important) aspects of a feature, I think option 3 is best as I’m not sure what value the grouping by type provides. This is made worse by the fact that as a reader, I might not fully understand the differences between the different types of documentation and thus a reader might be confused by that grouping (and, e.g., not understand why some parts are in “tutorial” and others are in “howtos”). Btw., from what I understand, “howto” is misspelled in all your examples, it should be “how-to” or “how to”.
Since each type of documentation only covers part of a feature, rather than the whole feature, you indeed need to combine pages from different types to get the complete feature. Because of this, I understand you would lean more to option 3.
So far, we’ve preferred writing “how to” without a hyphen, but indeed we need to decide on a consistent style. Thank you for bringing this to our attention!
So the Status for this is:
Option 1: Vincent, Simon, Manuel, Thomas, Lucas
Option 3: Pauline, Eleni, Michael
On the new location of documentation, in the navigation panel will be displayed only option 1 of the navigation tree. I’ll mark this as solved after I’ll update the doc guide.
Note that choosing Option 1 also requires to decide how to manage the landing pages for types on each topic. See this proposal as a continuation. In addition, don’t forget about that there needs to be an agreement on Positioning pages in nav tree too.
Finding an exact “importance” order when creating a new page could be tedious…
E.g. I’m creating a new doc. It’s a reference doc about the page history features. I write it, all is good. Now I need to position it relative to potentially a lot of other features. IMO, it’s more important than page exports, and less important than page notifications.I check the positions of those in the list. Someone else ordered those and thought that page notifications are more important than page exports… And I don’t have any “correct” place where I could put my new doc. I have no idea where to put my it, so I put it pretty much at random somewhere in between my two points of reference.
This is just an example, but I feel like similar situations could happen quite often and it would be quite a pain to apply such a loose rule in practice, which would probably end up just looking desorganized.
IMO, if we show all pages in the navigation from the start, then we want to use a simple order, alphabetic would work well (with the added benefit that we don’t need to admin the navigation tree every time we add any doc ).
If we limit pages on each branch of the navigation (with “show more” buttons), then it makes sense to pick the X first pages that should be shown first to the user and I agree with what you proposed.
+0 I’m hesitating on this one, as I like that doc writers don’t have to create type landing pages for each topic, even from a template), but I also find it confusing for them if the types are displayed in the navigation.
Indeed, with the types and audiences in the navigation (see the Proposal 7 about the navigation), then doc writers will have to create landing pages for topics and audiences, but not for types (created automatically).
Creating it manually for types also feels a bit more logical to me, even if it requires more time.
Honestly on this I think we shouldn’t impose a fix order based on some subjective criteria, because it will be a nightmare to maintain. So I would rely only on alphabetical order of pages so that we don’t need to maintain it at all: it will be handled by the tree macro.
I just want to make sure I understand correctly, could you please clarify a bit what you mean by items shown on one branch of the navigation? Are you referring to:
or to the implementation of the opening/closing of nav tree nodes? ( see Vincent’s comment about this.
I completely agree that choosing an order is really subjective and in practice, I don’t think we’ll ever get a perfect or “correct” order that everyone agrees on. But that’s exactly why we need some common criteria as guidelines for everyone, so that contributors have a clear reference when placing new docs. The idea is to make sure the structure grows in a consistent way and hopefully over time, we’ll end up with something that makes sense for everyone.
I’m not sure I fully agree. I like the idea of not having to manually manage the order every time, but I think for the reader it’s more helpful if the pages are listed by usefulness rather than alphabetically. OTOH, I do see another benefit of the alphabetical order, that it stays consistent with the breadcrumb.
Breadcrumbs also consider the pinned child pages so if we use this standard feature (vs. some custom code/list, not sure what the current plan is), the breadcrumbs would already be consistent.
