Recomendados
Recomendados
Más contenido relacionado
La actualidad más candente
La actualidad más candente (20)
Similar a Docs as-code-missing.-manual
Similar a Docs as-code-missing.-manual (20)
Último
Último (20)
Docs as-code-missing.-manual
- 1. Margaret Eker @meker meker12 Jennifer Rondeau @bradamante bradamant3 yourmom.io Docs as Code: The Missing Manual
- 5. “Docs as code” ?? Web delivery Continuous integration for documentation Collaboration for documentation using code systems Content management using code systems Definition of docs as code from Anne Gentle from her blog about modernizing technical documentation (https://justwriteclick.com/2016/08/13/modernizing-technical-documentation/)
- 6. “Docs as code” ?? Docs in repository together with or close to code Lightweight, plaintext markup language Build to HTML using simple static site generators (Jekyll, Harp) or doc generators (Sphinx, Asciidoctor) Multiple stakeholders Iterative (assumes agile development model)
- 7. –Noirin Plunkett,Write the Docs NA 2013 “I imagine most of you are writers, work with writers, know writers. I've been a professional writer for almost a decade ... and my process when i write something basically goes, I research, I draft, I read my draft, I edit my draft, I read my second draft, I edit that, I ask somebody who isn't an expert to read it, I edit based on their comments, I ask someone who is an expert to read it, I edit based on their comments. Hopefully I then read it again, because all of those edits sometimes need a final edit to kind of connect the pieces that have gotten disconnected.And then eventually I publish it. So what do all those edits give me, that I don't get when I just dash off an email? Some of them clarify content, some of them change the register ... some of them put in emotion ... we speak with our fingers.”
- 8. How do we reconcile? The “missing manual” -- map this kind of doc workflow to emerging model of docs-as-code Details missing from doc and code workflows Map doc workflow Map code workflow What can we learn?
- 10. Release planning Doc Req Doc Design Plan Design Templates, stylesheets, info architecture, content strategy, doc project plan, and schedule Requirements analysis Use cases, scope of work, required deliverables User stories + Code + Tests + Docs + UI + UX
- 11. Scope of work Audience Updates (bug fixes) New features New product or service
- 12. Design Specify types of documentation required Specify the content model, content type templates Understand deployment models
- 13. Development Write Doc Review Develop Review Developmental edit, technical review, design review, business review Develop Work with product and development team to research, create content (words, images, diagrams, and samples) User stories + Code + Tests + Docs + UI + UX
- 14. Assumptions Source formats Source storage Content models and templates Contributor collateral Training
- 15. Develop content Research Outline Write Submit (Commit, automated build deployed to staging)
- 16. Test Spell check Quality checklist User acceptance testing?
- 17. Review (pull request) Developmental edit Preliminary draft (self review) Technical review (user stories, product implementation) Editorial review (Style guide) Final review (Quality checklist)
- 18. DONE Doc Finalize Doc Publish Release Doc publish Integrate with product, push to production web site, package for distribution Final updates Apply final edits, sign off User stories + code + tests + docs + UI + UX
- 21. Code workflow Develop code architecture (design) Build out framework (or work with existing) Write tests Write code against tests (ideal) Build branch, run unit tests Debug Additional tests: integration, regression, acceptance Debug Merge to master
- 23. Documentation workflow Develop information architecture (“developmental edit”) Write first draft Send for review Revise/edit Send for additional reviews as needed Revise as needed Publish
- 25. docs learn from code Write locally Edit locally (?) Build branch locally Submit pull request Participate in PR discussion; discuss as appropriate in issues Revise Resubmit PR / respond to additional forks, PRs Repeat as needed Branch builds until PR merged to master
- 26. Hard part #1
- 27. Hard part #2 OMG I have all this super cool stuff to tell you and I can’t wait to explain All The Things. Here they are in no particular order: 1. I LOVE THIS API. 2. What’s an API? 3. I cannot figure out what this API does. I wish I didn’t have to write this documentation. I can’t figure out what to write. I hate writing. I love writing, but not this stuff. I am terrified, I cannot possibly let anyone else see this terrible stuff I don’t really understand but someone told me to write documentation so here I am. I cannot possibly let anyone else see this imperfect piece of dreck because I am really meant to be a poet but I am sadly lacking in a room of my own and 500 euros a year or whatever the current equivalent of Virginia Woolf’s bourgeois fantasy might be. So I write beautifully perfect technical documentation but this is not it so I refuse to put it on GitHub or otherwise let anyone else see it until it is absolutely perfect and complete.
- 29. doc tests Linters = the unit tests of documentation Integration tests for docs? Regression tests for docs? Acceptance tests for everybody?
- 31. DoCS AS Code for You? Docs as code development environment including CI/CD Content models and templates Shared project planning processes and systems Contributor collateral (Readme, Contributing information, Contributor Guide, Style Guide) Establish review guidelines and workflows (GitHub pull-request) Cross-training for contributors (Git for Teams, documentoring, and so on)
- 32. Resources
- 34. Hardest PART Establishing and maintaining open communication and collaboration across teams (Trust)
- 35. Write the Docs, together!
Notas del editor
- Starting doc project, regardless of our other roles on a software project, can often feel like this image — we’re eager to explore the forest and learn about the trees, but we often start out alone, and almost immediately stop at the beginning, a bit confused and uncertain about just what we’re seeing and where we’re supposed to go. Collaboration is obviously the foundation of this talk, it’s also about finding more ways for all of us to collaborate. Image credit: Carmen Marxuach @ https://unsplash.com/@carma16
- One of the things we can do, though, is to look to those who have come before us, or to our current colleagues, for information, support, and help. These are some of the most important folks who in many different ways have made this talk possible: by blogging extensively about doc practices, by supporting us as colleagues, by providing feedback on our talk. This is truly a collaborate effort, that extends beyond this list to, among others, everyone who’s involved with WTD. So … docs-as-code is not a new thing. Many people on this list have talked in varying levels of detail about managing docs with code, about treating docs as requirements for builds to pass, and about managing docs with code in continuous integration and continuous deployment.
- But we see ongoing opportunities to identify the trees of the docs-as-code forest more clearly, to understand more of the complexity of the forest ecosystems, and to build bridges between parts of the forest. And as it turns out, many of the talks at this conference have addressed some of these trees, and shown us ways to build new bridges — or mend old ones. Image credit: Tim Bogdanov @ https://unsplash.com/@timbog80
- Let’s start with some high-level review (or introduction, depending on your familiarity with this approach to docs). Anne Gentle has recently provided this nice summary of her work on the docs as code approach to software documentation. But it’s pretty high level.
- So we’ll add a few more items, to unpack some of the things on Anne’s list, and to describe a little more precisely what’s come to characterize docs-as-code in practice.
- On writing, first. Quote that I ended by talk with last year at WTD EU — seems appropriate in this different context too. One eloquent invocation of the writing workflow in its most idealized state. Note the research, the draft, the edits, the reviews … Key point here is that writing workflow is iterative. You don’t just write some stuff done and publish it if you want good usable docs. But … Notice anything? Notice how many steps in this flow are missing from many discussions of doc workflow? ESPECIALLY when we talk about docs as or with code? All too often documentation is a single line item in a project plan, if it’s acknowledged in the plan at all. Noirin’s steps are the real starting point of this talk, and the larger project that it’s a part of.
- But they’re only the starting point. Noirin’s words are about words, writing, docs. There’s some reconciliation needed here. You could say that there’s an ironic mismatch between “docs as code” in its single-line-item approach to the doc work, and the writing workflow as outlined by Noirin. Code is always iterative, but all too often the docs as code workflow still does not account for iterative nature of the writing part. So here’s Margaret to help us understand better how we can implement an iterative documentation process.
- Earlier, Rachel Whitton showed us how “Docs as code” can enable documentation to keep pace with Agile software development. However, it’s no guarantee of success. To be successful, the work required to plan, write, and deliver the content must be accounted for in the planning and development cycle. Docs are a line item in the release planning process. So let’s take a look at that line item and what it takes to get from release planning to done. Image credit: Sandis Helvigs @ https://unsplash.com/@sandishelvigs Rachel Whitton @ http://www.slideshare.net/RachelWhitton3/delivering-highvelocity-docs-that-keep-pace-with-rapid-release-cycles
- In the Release planning process, all components of the release and sprints are driven by user stories, including documentation. That means that you can scope doc work at the same time that you scope code, UI, and UX work.
- Often, doc release planning assumes the smallest, easiest scope —update existing documentation and submit it without further analysis. This assumption creates a problem when the scope is in fact the larger or more complex, for example documenting a new, large feature or a new product or service. Image credit: Michelle Spencer @ https://unsplash.com/@michellespencer77
- What kind of documentation do you need? User guide, reference guide, application developer guide, online help? Each type requires a content model defining the parts, structure, and organization and content type templates for reference, concept, task). Having these models and templates available enables people to contribute more easily and makes it easier for their contributions to be merged into existing content. The documentation development work must also account for how content is deployed. Is the content integrated into the UI, is it deployed as a stand-alone information set, or integrated into a larger documentation library? Build and deploy is another point of intersection in the doc and code workflow because documentation can leverage the same product and deployment models used for code products. For example, the Rackspace product documentation is a static website that is built, tested, and deployed like other web-based content. However, these models require review to make sure that they account for any additional requirements like integrated search or a user feedback feature.
- After release planning, let’s look at the Development phase— where you write, review, and test the content. Sprint planning for docs looks a lot like it does for code.
- You have an “docs as code” development environment in place that provides a GitHub workflow and CI/CD infrastructure to develop, build, and deploy content. You also have content models and templates that people can use to create content. Having this infrastructure makes decisions about source, storage, and deployment trivial for docs because you can leverage the same technologies used for the code, instead of having a completely separate set of tools and workflows specific to docs. However, all stakeholders need to ensure that the environment addresses doc requirements and needs, if they are to use the same one. Or that the doc dev environment has everything required. Some assumptions to enable doc development are: Code, docs, and other project tools and source are open to all contributors with the following infrastructure in place: Contributor collateral (README, CONTRIBUTING, and so on) Training available for anyone that contributes or reviews the documentation (GitHub training, writing assistance, contributor user documentation) Collection of templates and deliverable models (content specifications in OpenStack) available to customize and extend.
- Like code developers, writers research to understand user stories so that they can prepare to create doc content—the words, images, diagrams, samples, and other components of the documentation product. They also research and communicate with the product development team to understand how those stories are implemented in the code and delivered to users in the resulting product or service. Ideally, this work parallels and intersects with the coding work and is accounted for in the planning and scheduling. (Docs as code helps because developers can write the first draft based on what they know, and others can pick up the draft to develop and refine it.) Based on the research, writers create initial outlines based on the content models and templates appropriate for the project. (Things can slow down here, if you don’t have any content models or templates.)
- Looking at the test phase, highlights differences and gaps in documentation development and code development. To date, most doc testing has been done manually and has been limited to syntax and language checking incorporated into the writing and review process through grammar and spelling checks. When you treat docs like code, testing can become a distinct component that is integrated into the doc development process just as it is for code. Linters can be customized to perform the same test functions provided by writing-specific development tools, and there are many other opportunities to add tests to the doc workflow. Jennifer is going to talk more about this later.
- Doc review process has primarily been done manually, by multiple stakeholders if you’re lucky. A full service, red carpet review process starts with a developmental edit, which corresponds to the architecture and design review in a code workflow, down to the final review where you do final quality checking informed by a quality checklist. Content is reviewed against style guides, user stories, product implementation, standards, and checklists just as they are for code. Notice the number of reviews, by different people for different purposes.
- With treat docs like code, the final publishing is a button push. Because you have a continuous integration and continuous delivery workflow in place, you are building and deploying to staging every time you submit an update. When you are done, you push your content to the master branch, and it gets deployed to production instead of staging.
- So let’s look at Margaret’s material from a slightly different perspective, one that focuses on ecosystems of the doc and code forests, and how we can build bridges between them. Image credit: Tim Swan @ https://unsplash.com/@timswaanphotography
- Let’s start with code workflow. Image credit: Kim Greenhalgh @ https://unsplash.com/@kimg99
- So let’s look in a little more detail at one standard variation on coding workflow. Summary: Design, build/test, deploy Unit tests, debugging, integration and regression tests, debugging Acceptance tests!
- And doc workflow Image credit: Will Fuller @ https://unsplash.com/@wfuller
- Doc workflow. Noirin’s words translated more simply, perhaps. info arch, first draft, review, revision, additional review, additional revision, publish As we’ve seen from Margaret’s discussion, there are missing items here that she’s helped us identify. But here’s another thing -- we’re treating docs as code, right? So can code management or code workflows also help out here, to move from what one might call a classic writing workflow to a truly integrated approach to docs and code? Not just to integrate doc workflow, but even to improve it, and improve it in ways that help teams develop a real shared vocabulary.
- What does a bridge across them, one we can actually traverse, look like? Image credit: Christian Joudrey @ https://unsplash.com/@cjoudrey
- Yep, your standard-issue GitHub workflow. And yes, GitHub can help. We can think of it as the trestles of the bridge. But code and docs still wrestle with problematic pieces, missing parts. Margaret’s shown how we need style guides, not just for writing and editing, but for review. Pull Requests don’t in and of themselves take care of reviews, for docs or for code. We need standards, checklists, things everyone agrees are important to quality code and quality docs. And for docs specifically, we need ways to ease the parts that are hard for every contributor …
- Hard part #1: we’re all terrified of the blank page. This is where the templates and content models that Margaret has mentioned can help. These templates and content models map to the coding frameworks within which programmers work. This is ALSO where it’s absolutely crucial to remember that we are working with an iterative model. The first draft SHOULD NOT be the final draft!
- Yes, this is a ghastly wall of text. Don’t read it, that’s not what it’s for. The point is that it’s ghastly, but it represents a brain dump that someone else can look at and help parse for the doc content that really needs to be there. Just like pair programming. Just like code reviews.
- And last but not least, for docs especially as we/they learn from code, there’s an emerging greenfield opportunity …
- Probably the most under explored aspect of doc development in any environment, docs-as-code or not. Older doc tooling incorporated much of what linters now do, and linters are being extended and customized to provide more and more automated doc testing. More and more people, as we’ve seen in several of the talks at this conference, are looking more carefully at doc tests. But we still have a long way to go, and we’d like to suggest that docs can learn a lot from both the successes and the weak spots of code testing. You could call linters the unit tests of docs. But what about integration tests? Regression tests? Acceptance testing? Some of these things are pain points for everyone. Acceptance testing is especially neglected by everyone on a software project. And it’s crucial — we need to revisit project planning to be able to account adequately for it. But we also need integration and regression testing for docs. Bug fix documentation can go initially into release notes or fix notes, but eventually it needs to be incorporated into the main doc set. What if it doesn’t map well to the rest of your doc deliverables? To date doc solutions to this issue are manual, but it’s important to distinguish between this kind of testing and reviews, into which it’s often rolled. And when it comes to API docs, there’s still a surprising amount of work to do in testing, even with code examples where any number of automated solutions are available. Better yet, integrate code testing and code examples for your APIs — you don’t need to reinvent the wheel. We did this at Symantec, where the doc team helped write acceptance tests and where automated test scripts formed the foundation for the code examples that shipped with the API. Maybe, just maybe, doc testing can be a place where the forest ecosystems can merge, we can cross bridges freely, and code and docs can find more ways to collaborate and to share vocabulary and workflow.
- Image credit: https://unsplash.com/@mili_vigerova
- Docs as code doesn’t guarantee delivery of high quality, complete documentation, but it enables those working on docs and code to speak in the same terms, share the same tools, and take advantage of the speed and convenience that CI/CD workflows enable. Without any other changes, this significantly improves our chances of keeping documentation in sync with the code.
- This list includes a few examples and resources for creating a “docs as code” environment that we have relied on in our work.
- If you want to move to a “docs as code” environment and process, you cannot make all of these changes at once. You have to take a layered approach. Starting by setting up your “docs as code” environment and migrating or transforming your content to a new format. Followed by the other steps in the process, including the work to the change the way you communicate and coordinate across teams. This is hard work, and it feels more like carrying a bicycle through a cornfield than wandering down a beautiful forest path. This process can be challenging, and it might feel more like carrying a bike through a cornfield to get to the forest. However, the advantages of a common development environment and the efficiencies of CI/CD are well worth the effort. Image credit: Sandis Helvigs @ https://unsplash.com/@sandishelvigs
- The hardest part of transitioning to a docs as code approach to writing and delivering documentation is establishing and maintaining communication and collaboration across the coding and writing roles. However, without this communication and collaboration, the “docs as code” approach is likely to run into the same issues encountered with traditional workflows—documentation incomplete or unfinished at end of release cycle, silo’d teams, and customers who cannot find the information they need to use a product, service, or new feature.
- Image credit: Sandis Helvigs @ https://unsplash.com/@sandishelvigs