update homepage to describe each post

index.rst

@@ -10,30 +10,38 @@ A blog about technical writing by `Kayce Basques <https://kayce.basqu.es>`_.
 Accessibility
 -------------
 
-* :ref:`skip-to-main-content`
+* :ref:`skip-to-main-content`. A feature that makes your docs site much more
+  user-friendly to people who don't use mouses and only navigate with
+  keyboards.
 
 -------------
 Build systems
 -------------
 
-* :ref:`bazel`
+* :ref:`bazel`. Development log of my journey to migrate a docs site from a
+  GN-based build system to a Bazel-based one.
 
 .. _dac:
 
 ------------------
 Docs-as-Code (DaC)
 ------------------
 
-* :ref:`link-text-automation`
-* :ref:`verbatim-wrangling`
+* :ref:`link-text-automation`. A killer feature from Sphinx that more docs systems
+  should adopt.
+* :ref:`verbatim-wrangling`. My struggles to get a plaintext diagram rendering correctly
+  on a docs site that uses Sphinx, Breathe, and Doxygen.
 
 .. _dad:
 
 ------------------
 Docs-as-Data (DaD)
 ------------------
 
-* :ref:`intertwingularity`. 
+* :ref:`intertwingularity`. I’m building a web crawler so that I can track how pages in my docs
+  site link to each other and to the outside web more broadly. If a lot of my docs pages link to
+  some particular page, then that page is probably important. PageRank Lite, basically, except
+  with much more focus on intra-site backlinks.
 
 .. _ml:
 
@@ -44,12 +52,18 @@ Machine learning
 * :ref:`stateful-assistants`. GenAI chatbot assistants might be very useful if
   they can serve as companions for the entire journey that readers take when
   visiting my docs sites.
-* :ref:`evals`
-* :ref:`playing-nicely`
-* :ref:`plugins`
-* :ref:`principles`
-* :ref:`huggingface`
-* :ref:`style-guide-fine-tuning`
+* :ref:`evals`. How do you measure whether your retrieval-augmented generation system
+  is improving over time?
+* :ref:`playing-nicely`. Early ideas about how to author docs that work well with
+  generative models.
+* :ref:`plugins`. You can't control when ChatGPT uses your plugin. You can only maximize
+  the chance that ChatGPT uses your plugin by describing your API effectively.
+* :ref:`principles`. My response to Tom Johnson's "10 principles for writing for AI"
+  post.
+* :ref:`huggingface`. Initial experiments around summarizing text with HuggingFace
+  models.
+* :ref:`style-guide-fine-tuning`. How and why one might fine-tune a generative
+  model into a style guide editor.
 * :ref:`genai-outlook-2023`. My initial thoughts on how GenAI might affect
   technical writing.
 
@@ -59,21 +73,24 @@ Machine learning
 Search engine optimization
 --------------------------
 
-* :ref:`sentry-overflow`
-* :ref:`discovered-not-indexed`
+* :ref:`sentry-overflow`. Sentry, the app monitoring company, appears to be
+  competing with Stack Overflow.
+* :ref:`discovered-not-indexed`. How I fixed this error for ``pigweed.dev``.
 
 .. _ux:
 
 ---------------
 User experience
 ---------------
 
-* :ref:`methodology`. Background context for my field research.
+* :ref:`methodology`. How I approach my field research.
 * :ref:`searchboxes`. Where should I put the search box on my docs site?
   What placeholder text should it contain? What should happen when I type stuff
   into it? What should the search results look like?
-* :ref:`offline`
-* :ref:`pdf`
+* :ref:`offline`. There seems to be unmet demand for viewing documentation websites
+  without an internet connection.
+* :ref:`pdf`. Just append ``#page=X`` to your URL, where ``X`` is a placeholder
+  for the page you want to link to.
 
 .. toctree::
    :maxdepth: 1

ux/offline.rst

@@ -1,8 +1,8 @@
 .. _offline:
 
-============
-Offline docs
-============
+======================
+SWEs want offline docs
+======================
 
 2023 May 31