Documentation maintenance and curation

[salmad3]

Ideas on maintaining documentation

• Originally posted in How to keep docs up to date #5:

Problem: Documentation, by definition, creates a separate source of truth independent of the code. While we can autogenerate certain documentation like method signatures (e.g., godoc), there's no realistic automated system for documentation that broad areas like:

key concepts
system architecture (including diagrams, which are both expensive to maintain and highly valuable to readers)
how and why to use certain {classes|methods|subsystems}
how various pieces fit together
This issue is to collect ideas for what process(es) libp2p should put in place to stay up to date. I don't know what the best practice here is, but we should think about this early before it becomes an unmanageable nightmare.

Here are some ways I have seen this handled (none is perfect):

Minimize documentation - we should be careful about what we document. Especially diagrams, which are both expensive to change and extremely valuable to readers.

On diagrams specifically, we should look at having one (ideally open source) tool to create them and where we can keep the diagram "source" under version control and let people open PRs against it.
Another issue on diagrams is accessibility. We should try to have conventions around requiring alt text that explains what the diagram is intending to show. Unfortunately, this also has to be kept up to date.
Keep documentation isolated by topic - example: if the project adds support for a new NAT hole punching feature in 6 months, there should only be one article or article group that needs to be reviewed and updated.

Change log - each release[*] should have a change log. In different companies I've seen this done by engineering, product management, project management or documentation. I think the important point is just that we have some system by which one is being produced. Scripts can generate a list of all PRs between x and y git tags, but we need a human to group them together ("New: Feature X. This version adds support for feature X, which is [short description]. For more information, see [docs link] or these PRs [list...]")

[*] Currently we don't even have a formal release process for every implementation, so this is an area that goes beyond just documentation.

I've found that technical users like developers love change logs, especially ones that call out breaking changes. It softens the blow a lot when you change some behavior, even ones that were previously undocumented.

Versioned docs - this requires substantial extra infra work initially, but it's something to consider.

• Response by @yusefnapora:

Great points.

For diagrams, I've been looking at using mermaid, which is a text-based markup format for flow charts & interaction diagrams. It's not as flexible as something like dot / graphviz but is IMO simpler to read and write in its textual form. I haven't got very far with it yet, but hope to play with it some this week.

I think points 1 & 2 are both something to keep in mind as we structure the initial version - we should try to minimize dependencies between docs in the same way we'd think about module dependencies in code, if possible. One thing that could help would be for our "concept articles" to avoid discussion of implementation details as much as possible and instead lean on links to specs, etc, which change less frequently.

Things that seem especially likely to get out of date are the code-heavy tutorials we want to write, which will be frustrating for users if they don't track with code changes. We could look into having each tutorial be "backed" by a CI-testable example repo that gets triggered when its module dependencies publish new versions. Then we'd hopefully get an early warning if a release "breaks the docs". This requires a bit of setup and some discipline on the tutorial authors to make sure they're excerpting directly from the CI-tested example code.

Change logs are awesome - do we have any kind of script / tooling around this now?

By versioned docs, I'm assuming you mean docs that are for a specific libp2p release? That would be amazing. This ties into the formal release process you mentioned - if we can incorporate documentation updates into that process so we're confident that the docs are correct when we cut releases, we could keep a map of libp2p version numbers to IPFS links for each corresponding release of the docs site. In practice, we'd probably have separate "doc bundles" for each language implementation, with docs versions tracking that implementation's version number.

Style guide and conventions

• Originally posted in Add style guide / conventions #8

Not urgent, but at some point other people are going to start contributing to this documentation. If we have a set of writing conventions we want them to follow, it's much easier to lay down some ground rules in advance and then politely say in review "Can you revise this per our style guidelines [link]."

I would backlog this until we start getting a few outside contributions. That'll give a sense of what kind of weird (to us, but normal in the contributor's mind) types of writing we get.

• Response by @yusefnapora:

The ipfs/community repo has a docs styleguide we can look at adopting and tweaking

Contribution trampoline widget

• Originally posted in Wish: Contribution trampoline widget #10 by @raulk:

As people consume libp2p documentation, we should leverage the opportunity to get them to contribute to libp2p.

How to achieve this? By reducing friction between the time that people think “wow, this is interesting” (while reading), and they find a meaningful thing to contribute to.

Concept: a context-sensitive “widget” that integrates with Github in each section of our docs, and pulls a list of issues relevant to the content being viewed, tabbed by language so that people can jump straight into making contributions.

This requires annotating each page with metadata to link it to the relevant repos, and using the Github Search API to pull the data in.

So imagine you’re reading all about relays, and just at the bottom of the page (or elsewhere) there's a wishlist of features pulled from go-libp2p-circuit, js-libp2p-circuit, etc. to get you into hacking mode.

When people select a language tab, we should remember their language preference throughout the navigation.

Consider integrating with SourceCred for a gamified experience.

---

Following the above ideas

closing the prev. stale issues on the repo in favor of this discussion where we will lay out the best next steps and create targeted issues for each

• Create a contributors hub that includes:
  • Style and configuration guide
    • Style would focus on writing style and allow the overall style of documentation to grow organically from different contributions.
    • Configuration guide would focus on the Hugo configuration needed, such as a standard approach for the frontmatter and how to add/update docs.
  • Eventual instructions for translations/localization
  • Standard template for tutorials
  • Standard template for "concept docs"
• Add a changelog
• Unified diagrams (now in progress)
• Dynamic UI/UX for users & contributors, such as a widget

[marten-seemann]

@DannyS03 could you fix the formatting here? If you use code snippets (```), the lines will get super long and overflow. You could use quotes (>) instead, that would preserve line breaks.

[salmad3]

Good call, updated.