symbol-docs
symbol-docs copied to clipboard
symbol
New structure for the site
The folder (and the site) structure is unclear. For example, Using symbol-bootstrap should be in the Tools section, and References is a hotchpotch section.
At least:
- A welcome page with 3 big buttons asking what kind of user you are (USER, DEV, NODE OWNER).
- Once an audience has been selected, the left "global" menu will only show topics for that audience.
- I'm thinking on even using different header colors for each audience.
- A horizontal menu on the top clearly stating who is this targeted at.
- Remove the useless top horizontal menu we have now (Getting Started, Features, Guides, Tools, Help).
- Ideally, I'd like to remember what the user chose the last time he visited.
- Move each content page to its proper audience section, splitting them when they are mixed.
- Tools should have their own sections (Wallet, CLI, Bootstrap, ...)
- Reference should be API reference (REST, SDK, Serializers, ...)
- Faucet and Explorer could have a Tools page too, but that's handled in #518.
- Finally separate guides using SDK, CLI and Wallet!
Leave redirectors in place, so old links keep working if files are moved around.
From @0x6861746366574: I've been thinking about this a bit. I think the main things we want to communicate through our documentation is below. You can decide if it makes sense in 'one' framework (e.g. symbol.dev/documentation), or whether we should have some of this separated out. The idea is everything is public facing, but the target audience is either internal or external:
INTERNAL
- Company: (like the GitLab Handbook): this would be our operations; our values and culture; expense payments; tooling and software; GitHub usage and labels, etc. Think a mixture of the Valve Handbook + GitLab Handbook for content. I'd like to be able to incorporate images, too, if that's possible. This is really for internal employees, but we can have it external.
- Product: Detailed product documentation. This would be geared towards the product teams themselves - it's the rationale around the why and how of a product, versus user-facing technical documentation (i.e. how to operate the product). Stuff like bug report formats; user-testing guidelines; coding standards; analytics reports and updates, etc.
BOTH
- Whitepaper: I've put this external to 'company', because it will evolve into a bit of a monstrosity. They will be a combination of both scientific and academic rationale behind the system design and it's motivations (what it's trying to solve and/or accomplish); as well as technical reference (i.e block structure, transaction layout, consensus algorithms). We'd want to maintain these as individual sections and then be able to compile it into a LaTeX-formatted document for attachment.
EXTERNAL
- Clients: Detailed, user-facing technical documentation on the different server clients we'll have (C++, Rust, Go).
- SDKs: Detailed, user-facing technical documentation on our SDK's and APIs.
- Wallets: Detailed, user-facing technical documentation on our wallets and operation; errors and troubleshooting; bug-report templates, etc.
- Nodes: Detailed, user-facing technical documentation on our nodes; errors and troubleshooting; bug-report templates, etc.
PRODUCT SPECIFIC This documentation should be attached to the product-specific website (for example, block explorers and/or testnet).
Now that the Handbook is alive and kicking, we have a place to store all company (syndicate) stuff. For example, all the "Contributing" mess in the current tech docs should be moved there.
There's a cool new site in place (with dark mode and big buttons in the welcome page) but that's not the final shape. Most of the issues discussed here are yet to be tackled. Therefore this issue stays open.
This is a minute detail in the grander scheme, but I've noticed that the guide's Contribute and Symbol Handbook have a lot of overlap when it comes to developer / documentation contributions, but aren't as cross-linked as I'd expect..
I.e. Contribute > Contributing guidelines should contain or link to the content in The Symbol Handbook > Organization Contribution Guidelines.
A small piece to fix in the broader content restructuring not likely worth it's own PR.
Yeah, the Contribute section contains mostly old material that needs reviewing and re-structuring, that's why it's a bit hidden. Definitely there is overlap that should be fixed. Ideally, all contributing instructions go into the Contribute section, and the Handbook just points to it.