Restructure user guide into top-level guides, reference and explanation parts #9379

malteneuss · 2023-10-28T22:08:52Z

Another step of the user guide improvement initiative #9214:

Restructure Cabal documentation top-level parts

The goal is for users to easier find pages for typical problems through search engines and page navigation.

The top-level layout is based on the popular documentation structure by https://documentation.divio.com/ to give a
clear structure to users and future documentation contributors:
- Guides: Present a solution to a single, atomic, typical user problem.
- Reference: Describe user API (CLI fields, syntax etc) with technical rigour and completeness.
- Explanation: Discuss background information, scope, design decisions etc.
Move existing documentation roughly into these categories with minimal editing as the basis for further editing.
Rename guide titles to mention how-to for improving SEO.
Rename some files to improve SEO since that name becomes part of the URL (often called slug).
Important page keywords should appear in the slug as well to make pages rank higher in search engines.

Template Β: This PR does not modify cabal behaviour (documentation, tests, refactoring, etc.)

Include the following checklist in your PR:

Patches conform to the coding conventions.

ffaf1

I appreciate the new TOC

doc/_templates/layout.html

doc/cabal-package-description-file.rst

doc/conf.py

doc/how-to-report-bugs.rst

doc/cabal-package-description-file.rst

geekosaur · 2023-10-28T23:07:31Z

doc/how-to-integrate-into-nix.rst

@@ -1,5 +1,5 @@
-Nix Integration
-===============
+How to integrate Cabal into Nix


Do we need this? IIRC there's a ticket noting that the functionality is broken and suggesting to delete it.

I kept it for now to show how a consistent guide naming could look like. I'd like to remove it in a separate PR, copy over possibly useful information into the Nix docs, and a reference here.

There is already an open PR for the deletion of this section (which also removes the nix integration from cabal itself) here: #9239

Yes, I think, it's better to remove it ASAP (at least the docs): it's a wart that is actively harming ux.

geekosaur · 2023-10-28T23:08:25Z

doc/how-to-package-haskell-code.rst

+.. TIP::
+    If this is your first time using `cabal` you should check out the :doc:`Getting Started guide <getting-started>`.
+
+Starting from scratch, we're going to walk you through creating a simple


This sounds like it is the Getting Started guide.

On second thought, given @ffaf1's comment on a deleted line, this whole thing is just relocated and this confusion was already there. We should probably still figure out what we want.

Yeah, the idea is that the getting started is a heavily condensed version of the more detailed package guide, just enough to get a feel for the tool/library

doc/how-to-package-haskell-code.rst

geekosaur · 2023-10-28T23:32:29Z

doc/how-to-package-haskell-code.rst

+-  ``pkgname >=n``
+-  ``pkgname ^>=n`` (since Cabal 2.0)
+-  ``pkgname >=n && <m``
+-  ``pkgname ==n.*`` (since Cabal 1.6)


Do we care about the "since" here?

Not, sure, but i like to add more explicit examples in a later PR. Let's keep it for now as is.

If it's not the reference part of the manual, things like since Cabal 1.6 are better omitted. Of course, if you feel like leaving it as a future work, that's fine.

malteneuss · 2023-10-29T21:23:44Z

I've cleaned up the commits

ffaf1

edit: not a good idea, ignore this

Can you try this for extra clarity?
If it is a mess you can reset the commit.

Comparison:

(tbd)

doc/cabal-package-description-file.rst

doc/cabal-project-description-file.rst

ffaf1

The new TOC with 4+2 main sections is very good.

ulysses4ever

I like the overall direction, but it’s a little hard to navigate all the changes. Please, expand the description of the PR (+ the commit message, which I haven’t checked, but should be identical to the PR description), and explain what exactly this achieves. References to 3rd party sites is allowed but the description should be self-contained nevertheless. Right now it’s not.

one clear flaw in the current PR is renaming of the source files. Let’s probably try to avoid this since it’ll break a lot of links to the latest version of the docs. The name of the file doesn’t need to match the name of the section.

ulysses4ever · 2023-10-29T23:44:03Z

Since it’s a significant restructure of our main documentation source, I invite the main contributors to chime In @Kleidukos @Mikolaj @fgaz @gbaz @andreasabel @andreabedini

BinderDavid · 2023-10-30T08:15:56Z

I really like the new TOC! I played around a bit with using captions, i.e. using the following index.rst:


Welcome to the Cabal User Guide
===============================

.. toctree::
   :caption: Getting Started
   :numbered:

   getting-started

.. toctree::
   :caption: Cabal Guide
   :numbered:

   how-to-package-haskell-code
   how-to-build-like-nix
   how-to-integrate-into-nix
   how-to-report-bugs

.. toctree::
   :caption: Cabal Reference
   :numbered:

   cabal-package-description-file
   cabal-project-description-file
   cabal-config-and-commands
   setup-commands
   file-format-changelog
   buildinfo-fields-reference

.. toctree::
   :caption: Cabal Explanation
   :numbered:

   cabal-context
   package-concepts
   cabal-interface-stability

This yields the following look:

The problem is that the sections aren't consecutively numbered on the left, but this layout might be an alternative.

Mikolaj · 2023-10-30T11:08:30Z

I love the restructure.

BTW, I wonder how the structure in the aborted project https://github.com/haskell/cabal-userguide compares with this one? Does it correspond to just the "Cabal Guilde" part? Is there anything to be learned or scavenged? @JonathanLorimer, would you have any remarks about the new restructure proposed in this ticket or generally an advice from a veteran?

ulysses4ever · 2023-10-30T13:20:16Z

I like David's version more. There's no reason to number the highest-level sections like Guide / Reference / Explanation in my opinion.

malteneuss · 2023-10-30T21:31:20Z

I really like the new TOC! I played around a bit with using captions, i.e. using the following index.rst:
...
The problem is that the sections aren't consecutively numbered on the left, but this layout might be an alternative.

That's a really nice layout. I've copied it over.

malteneuss · 2023-10-30T22:34:40Z

I like the overall direction, but it’s a little hard to navigate all the changes. Please, expand the description of the PR (+ the commit message, which I haven’t checked, but should be identical to the PR description), and explain what exactly this achieves. References to 3rd party sites is allowed but the description should be self-contained nevertheless. Right now it’s not.

one clear flaw in the current PR is renaming of the source files. Let’s probably try to avoid this since it’ll break a lot of links to the latest version of the docs. The name of the file doesn’t need to match the name of the section.

I've expanded the PR message and squashed the relevant commits to use that same message.

Regarding file renames i've added SEO as the reason. Our aim should be to have our latest Cabal pages rank highest for typical search queries like "how to package Haskell", "cabal file", and related variations instead of GHC, stack or blogs.

malteneuss · 2023-10-30T22:43:56Z

I love the restructure.

BTW, I wonder how the structure in the aborted project https://github.com/haskell/cabal-userguide compares with this one? Does it correspond to just the "Cabal Guilde" part? Is there anything to be learned or scavenged? @JonathanLorimer, would you have any remarks about the new restructure proposed in this ticket or generally an advice from a veteran?

The structure of that alternative looks like what the authors of https://documentation.divio.com/ would call a tutorial, teaching a user step-by-step more and more involved usages of Cabal. This may not be needed with Cabal, although some the topics would make good guides as well.

BinderDavid · 2023-10-30T22:53:35Z

I said something similar in #9214 already, but I think that this is an absolutely essential step in improving the documentation of cabal. Large sections in the manual can currently not decide whether they want to be a tutorial or guide introducing how to accomplish some task, or whether they want to be the reference documentation which exhaustively enumerates all the knobs and options. Making this explicit, like this PR does, is helpful in spotting and naming these discrepancies and fixing them in subsequent smaller PRs. Thanks @malteneuss for doing this :)

julialongtin · 2023-10-30T23:00:57Z

hmm. was just trying to use these docs (i have an upstream package with a bug in it). i uploaded it to a remote git repository, and wanted to tell cabal to use that version instead of the one from hackage, but the language around Specifying Packages from Remote Version Control Locations left me confused. "where do i put the name of the package?"

i think "specifying packages from an external version control" was missing an action verb. "specifying packages for cabal to download from an external version control" would have been clearer, along with some language about cabal matching the name of the package you're trying to use by first downloading the package, then looking at the cabal file there.

malteneuss · 2023-10-31T17:01:22Z

hmm. was just trying to use these docs (i have an upstream package with a bug in it). i uploaded it to a remote git repository, and wanted to tell cabal to use that version instead of the one from hackage, but the language around Specifying Packages from Remote Version Control Locations left me confused. "where do i put the name of the package?"

i think "specifying packages from an external version control" was missing an action verb. "specifying packages for cabal to download from an external version control" would have been clearer, along with some language about cabal matching the name of the package you're trying to use by first downloading the package, then looking at the cabal file there.

This is out of scope for this PR, but such question should definitely be answered by the docs. Could you add a separate PR against the existing docs? Maybe also adding what other "type" of version control is supported? Ideally the phrasing would use keywords that you would use to search with when you had no idea about the docs.

The goal is for users to easier find pages for typical problems through search engines and page navigation. - The top-level layout is based on the popular documentation structure by https://documentation.divio.com/ to give a clear structure to users and future documentation contributors: * Guides: Present a solution to a single, atomic, typical user problem. * Reference: Describe user API (CLI fields, syntax etc) with technical rigour and completeness. * Explanation: Discuss background information, scope, design decisions etc. - Move existing documentation roughly into these categories with minimal editing as the basis for further editing. - Rename guide titles to mention how-to for improving SEO. - Rename some files to improve SEO since that name becomes part of the URL (often called slug). Important page keywords should appear in the slug as well to make pages rank higher in search engines.

ulysses4ever · 2023-12-15T16:15:34Z

I just noticed that this patch did break URLs like https://cabal.readthedocs.io/en/X/cabal-project.html. Compare:

It may be good to look into restoring them using some Sphynx magic (there should be a way to assign URLs, I believe).

malteneuss · 2023-12-19T16:28:11Z

I can take a look, probably on the weekend. Thanks for reporting.

ulysses4ever · 2023-12-19T18:08:42Z

@malteneuss that would be awesome, thank you!

malteneuss requested review from ffaf1 and geekosaur October 28, 2023 22:09

malteneuss added documentation re: devx Improving the cabal developer experience (internal issue) re: readthedocs Concerning hosting documentation on `readthedocs` labels Oct 28, 2023

This was referenced Oct 28, 2023

Remove section "Bugs and Stability" from user guide #9354

Open

[Initiative] Improve Cabal documentation structure to become more beginner-friendly #9214

Open

ffaf1 reviewed Oct 28, 2023

View reviewed changes

geekosaur requested changes Oct 28, 2023

View reviewed changes

malteneuss force-pushed the top-level-guides-and-reference branch 2 times, most recently from 17cc303 to 82371cf Compare October 29, 2023 21:21

malteneuss requested review from geekosaur and ulysses4ever October 29, 2023 21:24

ffaf1 reviewed Oct 29, 2023

View reviewed changes

doc/cabal-package-description-file.rst Show resolved Hide resolved

doc/cabal-project-description-file.rst Show resolved Hide resolved

ffaf1 approved these changes Oct 29, 2023

View reviewed changes

ulysses4ever reviewed Oct 29, 2023

View reviewed changes

geekosaur approved these changes Oct 30, 2023

View reviewed changes

malteneuss force-pushed the top-level-guides-and-reference branch from d036b0a to 2b5a8a9 Compare October 30, 2023 22:29

malteneuss force-pushed the top-level-guides-and-reference branch from 76f48d4 to 8b47c3c Compare November 2, 2023 22:02

malteneuss added the merge me Tell Mergify Bot to merge label Nov 2, 2023

malteneuss force-pushed the top-level-guides-and-reference branch from 8b47c3c to 3b89724 Compare November 3, 2023 20:58

mergify bot added the merge delay passed Applied (usually by Mergify) when PR approved and received no updates for 2 days label Nov 5, 2023

malteneuss added 2 commits November 5, 2023 20:59

Rename master_doc to root_doc (changed in version 4.0 of Sphynx)

759ba8e

Mikolaj force-pushed the top-level-guides-and-reference branch from 3b89724 to 759ba8e Compare November 5, 2023 20:59

mergify bot merged commit 2fca50b into haskell:master Nov 5, 2023
44 checks passed

BinderDavid mentioned this pull request Nov 6, 2023

Move documentation about how to use backpack #9400

Merged

malteneuss mentioned this pull request Jan 12, 2024

Cabal documentation has some broken links when changing between latest and other versions #9613

Open

geekosaur mentioned this pull request Aug 2, 2024

Cabal ignores buildinfo in top-level of directory #10238

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Restructure user guide into top-level guides, reference and explanation parts #9379

Restructure user guide into top-level guides, reference and explanation parts #9379

malteneuss commented Oct 28, 2023 •

edited

Loading

ffaf1 left a comment

geekosaur Oct 28, 2023

malteneuss Oct 29, 2023 •

edited

Loading

BinderDavid Oct 30, 2023

ulysses4ever Oct 30, 2023

malteneuss Oct 30, 2023

geekosaur Oct 28, 2023

geekosaur Oct 28, 2023

malteneuss Oct 29, 2023 •

edited

Loading

geekosaur Oct 28, 2023

malteneuss Oct 29, 2023

ulysses4ever Oct 29, 2023

malteneuss Oct 30, 2023

malteneuss commented Oct 29, 2023

ffaf1 left a comment •

edited

Loading

ffaf1 left a comment

ulysses4ever left a comment

ulysses4ever commented Oct 29, 2023

BinderDavid commented Oct 30, 2023

Mikolaj commented Oct 30, 2023

ulysses4ever commented Oct 30, 2023

malteneuss commented Oct 30, 2023

malteneuss commented Oct 30, 2023

malteneuss commented Oct 30, 2023

BinderDavid commented Oct 30, 2023

julialongtin commented Oct 30, 2023

malteneuss commented Oct 31, 2023

ulysses4ever commented Dec 15, 2023

malteneuss commented Dec 19, 2023

ulysses4ever commented Dec 19, 2023

Restructure user guide into top-level guides, reference and explanation parts #9379

Restructure user guide into top-level guides, reference and explanation parts #9379

Conversation

malteneuss commented Oct 28, 2023 • edited Loading

ffaf1 left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

malteneuss Oct 29, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

malteneuss Oct 29, 2023 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

malteneuss commented Oct 29, 2023

ffaf1 left a comment • edited Loading

Choose a reason for hiding this comment

ffaf1 left a comment

Choose a reason for hiding this comment

ulysses4ever left a comment

Choose a reason for hiding this comment

ulysses4ever commented Oct 29, 2023

BinderDavid commented Oct 30, 2023

Mikolaj commented Oct 30, 2023

ulysses4ever commented Oct 30, 2023

malteneuss commented Oct 30, 2023

malteneuss commented Oct 30, 2023

malteneuss commented Oct 30, 2023

BinderDavid commented Oct 30, 2023

julialongtin commented Oct 30, 2023

malteneuss commented Oct 31, 2023

ulysses4ever commented Dec 15, 2023

malteneuss commented Dec 19, 2023

ulysses4ever commented Dec 19, 2023

malteneuss commented Oct 28, 2023 •

edited

Loading

malteneuss Oct 29, 2023 •

edited

Loading

malteneuss Oct 29, 2023 •

edited

Loading

ffaf1 left a comment •

edited

Loading