Comments (3)
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.
from docs.
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.
from docs.
Closing in favor of: #208.
from docs.
Related Issues (20)
- Internal Markdown links not working HOT 3
- Audit all links HOT 2
- How to generate peerID
- Add DCUtR info to glossary
- Revisit muxer overview text
- Webfonts return 404
- go-libp2p ping-pong no good addresses error HOT 1
- add `/ipfs/0.1.0` to protocols page HOT 3
- js-libp2p ping-pong - TypeError: node.ping is not a function HOT 7
- Broken link HOT 5
- Describe NAT hole punching in the NAT overview
- Homogenize link style
- Incorrect go version requirement
- Broken Link
- Ping section is shuffled in documentation page
- Broken Link
- Getting Started js-libp2p: ERR_PACKAGE_PATH_NOT_EXPORTED
- Question in Stream Multiplexing HOT 1
- Add an example for hole punching
- Upgrade Doks theme
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from docs.