Qubes-Doc: Developer Documentation is hiding

[Jeeppler]

Most of the Developer Documentation is hiding behind the link to System Documentation. This is unexpected since every other article is reachable with two clicks.

The problem is, if you don't know that subjects like debugging or the architecture is behind the System Documentation link, you will miss it.

[marmarek]

👍 for moving all of them into main doc index. Then "For Developers" should be probably some bigger title, to still have sections below.

[marmarek]

👍 for moving all of them into main doc index. Then "For Developers" should be probably some bigger title, to still have sections below.

[Jeeppler]

Okay, I will move them.

[Jeeppler]

Okay, I will move them.

[andrewdavidwong]

Then "For Developers" should be probably some bigger title, to still have sections below.

The problem is that @rootkovska specifically requested no deeper section levels. We redesigned the current ToC to satisfy that requirement, and this would directly contradict that.

This problem was supposed to be solved by moving the developer documentation to a different place than the user documentation: #1931

IMHO, this should be closed as a duplicate of #1931.

[andrewdavidwong]

Then "For Developers" should be probably some bigger title, to still have sections below.

The problem is that @rootkovska specifically requested no deeper section levels. We redesigned the current ToC to satisfy that requirement, and this would directly contradict that.

This problem was supposed to be solved by moving the developer documentation to a different place than the user documentation: #1931

IMHO, this should be closed as a duplicate of #1931.

[Jeeppler]

requested no deeper section levels

yes, there are two ToC levels. Either ===== for large or ------- for smaller. The qubes doc.md uses only ---- why not using ===== for the developer section?

No, don't close this and it is really not a duplicate of #1931 since this is not about finding a central place for API documentation as well as developer documentation. This issue is all about the idea of putting 70% of the developer documentation behind the System Documentation link. That does not make sense. Putting everything behind a single link is completely counter intuitive, since all other articles are just two clicks away. But you have to know that Qubes Architecture Overview is behind System Documentation and three clicks away.

@marmarek understood the issue problem in the first place.

[Jeeppler]

requested no deeper section levels

yes, there are two ToC levels. Either ===== for large or ------- for smaller. The qubes doc.md uses only ---- why not using ===== for the developer section?

No, don't close this and it is really not a duplicate of #1931 since this is not about finding a central place for API documentation as well as developer documentation. This issue is all about the idea of putting 70% of the developer documentation behind the System Documentation link. That does not make sense. Putting everything behind a single link is completely counter intuitive, since all other articles are just two clicks away. But you have to know that Qubes Architecture Overview is behind System Documentation and three clicks away.

@marmarek understood the issue problem in the first place.

[andrewdavidwong]

yes, there are two ToC levels. Either ===== for large or ------- for smaller. The qubes doc.md uses only ---- why not using ===== for the developer section?

Because that would create another level of nesting of the type @rootkovska requested that we not have. We're not talking only about heading levels here. The actual bulleted list also counts as a level. So, currently we have two "levels," and we're not supposed to have any more than that. (Adding h1 heading would create a third.)

No, don't close this and it is really not a duplicate of #1931 since this is not about finding a central place for API documentation as well as developer documentation.

No, but it would be (and is supposed to be) solved by solving that issue.

This issue is all about the idea of putting 70% of the developer documentation behind the System Documentation link. That does not make sense. Putting everything behind a single link is completely counter intuitive, since all other articles are just two clicks away. But you have to know that Qubes Architecture Overview is behind System Documentation and three clicks away.

It makes sense on the assumption that this page is intended to host primarily user documentation and that it should appear as "friendly" as possible to non-developer end users. That's the rationale for the "flat" (i.e., non-nested) structure, and it's also the rationale for "hiding" most of the developer documentation in System Documentation. This was supposed to be a temporary fix until we could move all the developer documentation to its new home (e.g., dev.qubes-os.org).

What doesn't make sense is ignoring the history of this situation and throwing out the current system when that simply re-creates the very problem that the current system was implemented to solve. Instead of re-creating the initial problem (which we will then have to re-solve), we should just finish implementing the full solution that we've already started implementing.

[andrewdavidwong]

yes, there are two ToC levels. Either ===== for large or ------- for smaller. The qubes doc.md uses only ---- why not using ===== for the developer section?

Because that would create another level of nesting of the type @rootkovska requested that we not have. We're not talking only about heading levels here. The actual bulleted list also counts as a level. So, currently we have two "levels," and we're not supposed to have any more than that. (Adding h1 heading would create a third.)

No, don't close this and it is really not a duplicate of #1931 since this is not about finding a central place for API documentation as well as developer documentation.

No, but it would be (and is supposed to be) solved by solving that issue.

This issue is all about the idea of putting 70% of the developer documentation behind the System Documentation link. That does not make sense. Putting everything behind a single link is completely counter intuitive, since all other articles are just two clicks away. But you have to know that Qubes Architecture Overview is behind System Documentation and three clicks away.

It makes sense on the assumption that this page is intended to host primarily user documentation and that it should appear as "friendly" as possible to non-developer end users. That's the rationale for the "flat" (i.e., non-nested) structure, and it's also the rationale for "hiding" most of the developer documentation in System Documentation. This was supposed to be a temporary fix until we could move all the developer documentation to its new home (e.g., dev.qubes-os.org).

What doesn't make sense is ignoring the history of this situation and throwing out the current system when that simply re-creates the very problem that the current system was implemented to solve. Instead of re-creating the initial problem (which we will then have to re-solve), we should just finish implementing the full solution that we've already started implementing.

[Jeeppler]

@andrewdavidwong if you move the documentation to dev.qubes-os.org that is fine. I would have fixed the issue by marking the For developers section as h1, but this is just my opinion.

[Jeeppler]

@andrewdavidwong if you move the documentation to dev.qubes-os.org that is fine. I would have fixed the issue by marking the For developers section as h1, but this is just my opinion.

[marmarek]

I think completely separating developer documentation (moving away to a different domain) is not a good idea at all. There are multiple pages that would be hard to decide where should go. For example (from "For developers" section):

• Reporting Security Issues
• Reporting Bugs
• Source Code
• Qubes OS License

And also some of "System Doc" may be useful for users too, for example:

• Security-critical elements of Qubes OS
• Qrexec: command execution in VMs

If moving anywhere, just create second index, similar to user index and have all the developer pages linked from there (possibly duplicating some of the links with the user index). Or move in opposite direction to have a single index, separated with some "For Developers" header - for that I'd ask @rootkovska for an exception from "2 levels only" rule.

[marmarek]

I think completely separating developer documentation (moving away to a different domain) is not a good idea at all. There are multiple pages that would be hard to decide where should go. For example (from "For developers" section):

• Reporting Security Issues
• Reporting Bugs
• Source Code
• Qubes OS License

And also some of "System Doc" may be useful for users too, for example:

• Security-critical elements of Qubes OS
• Qrexec: command execution in VMs

If moving anywhere, just create second index, similar to user index and have all the developer pages linked from there (possibly duplicating some of the links with the user index). Or move in opposite direction to have a single index, separated with some "For Developers" header - for that I'd ask @rootkovska for an exception from "2 levels only" rule.

[Jeeppler]

Some of the documents should be in a "For Contributors" section. Something like:

• Documentation Guidelines
• Reporting Bugs
• Qubes OS License
• Sytle Guide
• Usability & UX is not necessarily a developer only subject, this involves designer and artist as well

[Jeeppler]

Some of the documents should be in a "For Contributors" section. Something like:

• Documentation Guidelines
• Reporting Bugs
• Qubes OS License
• Sytle Guide
• Usability & UX is not necessarily a developer only subject, this involves designer and artist as well

[marmarek]

Some of the documents should be in a "For Contributors" section

This is exactly why I've said it's hard to distinguish user/developer documentation...

[marmarek]

Some of the documents should be in a "For Contributors" section

This is exactly why I've said it's hard to distinguish user/developer documentation...

[Jeeppler]

what about the following instead of just System Documentation renaming the link to System Documentation (multiple developer documents), which is maybe not perfect, but better than the current solution.

[Jeeppler]

what about the following instead of just System Documentation renaming the link to System Documentation (multiple developer documents), which is maybe not perfect, but better than the current solution.

[marmarek]

Or move in opposite direction to have a single index, separated with some "For Developers" header - for that I'd ask @rootkovska for an exception from "2 levels only" rule.

I've got approval for this exception :)

[marmarek]

Or move in opposite direction to have a single index, separated with some "For Developers" header - for that I'd ask @rootkovska for an exception from "2 levels only" rule.

I've got approval for this exception :)

[andrewdavidwong]

I think completely separating developer documentation (moving away to a different domain) is not a good idea at all.
[...]

This was @rootkovska's idea, not mine. Personally, I think it could work either way. It all depends on how it's implemented.

If @rootkovska no longer cares about moving all dev docs to a dedicated place, then that changes everything (both here and in #1931).

[andrewdavidwong]

I think completely separating developer documentation (moving away to a different domain) is not a good idea at all.
[...]

This was @rootkovska's idea, not mine. Personally, I think it could work either way. It all depends on how it's implemented.

If @rootkovska no longer cares about moving all dev docs to a dedicated place, then that changes everything (both here and in #1931).

[andrewdavidwong]

I've moved all developer documentation to the main index. Let me know if anything more needs to be done.

[andrewdavidwong]

I've moved all developer documentation to the main index. Let me know if anything more needs to be done.

[marmarek]

Thanks!

[marmarek]

Thanks!