The Big Writer's Guide Update #763
Conversation
Removed mention of italics from basics.adoc Rewrote attributes-and-roles.adoc Rewrote pages.adoc Created a partial to share between those two pages, available-attributes.adoc, to document the attributes in use in Couchbase docs
Removing footnotes example because we don't use them. Creating links.adoc example Tweaking examples in add-pages.adoc to be more specific. Rewriting basics.adoc to cover all of the markup we actually use.
… references, and editing documentation pages. Reworked the contributing workflow for creating branches, installing antora, installing Git and an editor, configuring a playbook, configuring repositories, and building a test site. Updated component terms. Updated images to stop using Atom references and use VS Code. Reworked the nav to stop having 2 different places for building the documentation site.
There was a problem hiding this comment.
This looks fabulous and very thorough.
I've skimmed through, and can't see any reason not to 👍 it -- I've not looked at it closely, and the preview link seems to be wrong?
But it's undoubtedly better than what we had, and I think we should merge and iterate on it.
(Happy to chat if there's any specific sections you'd like critique on though!)
One thought: I've found taking people through github Personal Access Tokens confusing... ssh keys work great for me, and gh repo clone is, honestly, much much easier than anything else (though it involves now having 2 command line commands, so perhaps your mileage may vary).
That's just to suggest you try that out at some point, and see if you think it's worth documenting in parallel/replacing? Happy to contribute that if helpful.
See a preview here: https://preview.docs-test.couchbase.com/home/contribute/index.html
I spent this week going through and trying to clean up some of the key parts of the writer's guide, to better support some of the new joiners that we'll be having go through getting set up with Antora.
Feel free to call out other changes you'd like to see.