15 |
22 | {% include footer.html %}
23 | {% include scripts.html %}
24 |
16 | {% include skip-links.html %}
17 | {% include navigation.html %}
18 |
19 | {{ content }}
20 |
21 |
15 |
26 | {% include footer.html %}
27 | {% include scripts.html %}
28 |
16 | {% include skip-links.html %}
17 | {% include navigation.html %}
18 |
25 | {{ page.title }}
19 |
20 | 
21 |
22 | {{ content }}
23 |
24 |
21 | 
44 | ```
45 |
46 | But native Markdown doesn't support adding CSS. Of course, Markdown *does* support inline HTML, and we *could* have just written HTML whenever we wanted to add an animated GIF. But, again, **I'm stubborn**. I like my Markdown to be clean. I didn't want to go down a slippery slope of adding special cases for departing from pure Markdown.
47 |
48 | Now, there are two parameters that you give an image in Markdown: the file name, which I needed to tell it where the file is, and alt text, which we often leave blank (I know... accessibility). So I decided to customize the jquery function that initialized gifplayer. Instead of looking for images with a CSS class called 'gif', it would look for images with alt text set to 'gif'.
49 |
50 | Like this:
51 |
52 | ```javascript
53 |
58 | ```
59 |
60 | So, now, if we write:
61 |
62 | ```markdown
63 | 
64 | ```
65 | it triggers the `gifplayer` script!
66 |
67 | 
68 |
69 | Sorry, we didn't implement the pause/play capability on this site, so that banana is gonna keep on dancing.
70 |
--------------------------------------------------------------------------------
/_posts/articles/2017-08-19-when-to-wiki.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: post
3 | title: What about wikis? Content management and change management
4 | excerpt: "Anne Gentle, the original wiki aficionado from the mid-2000s, discusses their relevance today."
5 | last_modified_at: Sat Aug 19 20:07:50 CDT 2017
6 | categories: articles
7 | author: anne_gentle
8 | tags: [documentation, docs, wiki, open source]
9 | image:
10 | path: /images/spacewalk-nasa2explore.jpg
11 | caption: "[NASA Johnson](https://flic.kr/p/iKTgKf)"
12 | comments: true
13 | share: true
14 | ---
15 |
16 | While I was writing _Docs Like Code_, I went back and forth in my mind, arguing with myself on whether the timing was quite right. I didn't know for certain if we had reached a tipping point as an industry, or if I was simply seeing a trend relevant only to the open-source, developer-centric world I was embedded in.
17 |
18 | And then, I heard from Gene in an email.
19 |
20 | > "Whenever I start considering retirement, again, I read one of your articles
21 | > and get inspired to keep going. Thank you for your interesting ideas and
22 | > willingness to share them."
23 |
24 | And he kept me going and asked more questions as I went, and I felt energized once again to answer his question about wikis and writing closer to the code.
25 |
26 | Gene goes on to share his background, which resonates with both software developers and technical writers who were once some other profession.
27 |
28 | > "The Docs Like Code theme resonates with me as a former software developer
29 | > and having always been embedded with developers as a tech writer. I think
30 | > it's easier for a developer-writer to buy into the concept than the
31 | > traditional tech writer can because the tools and methodology are already
32 | > familiar. Myself, I mostly converted because the critical mass behind
33 | > Markdown became too great to continue battling against it. My ideas of a
34 | > better way gave way to being open to using GitHub and
35 | > Markdown/reStructuredText, and looking for opportunities to make that
36 | > workflow better."
37 |
38 | Gene positively nails the place many of us find ourselves today. Converted or converting, migrating from one familiar toolset to another, a less familiar one, and taking the best from one workflow to another workflow to streamline the tasks at hand.
39 |
40 | We are living through change management in our content management.
41 |
42 | He goes on to ask, with double-spaces after periods, which I find endearing,
43 |
44 | > "I still have companies asking about using a wiki for documentation when
45 | > considering jettisoning their legacy documentation tools, which aren't
46 | > working. I'm able to dissuade them by saying the proliferation of content
47 | > soon becomes unmanageable, and they accept that because they assume I know
48 | > what I'm talking about and they don't when it comes to documentation. Many
49 | > of the arguments for using a wiki are the same you give in the Docs Like Code
50 | > articles; primarily, collaboration and ease of use."
51 |
52 | > "What are your thoughts on the differences between using a wiki and using
53 | > Git/Markdown, that I might be able to give them more substantive arguments?"
54 |
55 | This is a good question. I love the phrasing of this question because it does not pre-suppose a value judgment on either method.
56 |
57 | If I were in his shoes, I'd be curious and ask questions about the reasons for jettisoning -- is it because of licensing, authoring, or deliverables they can get from legacy? Or maybe there is a combination of reasons I can't come up with? That's interesting, and of course, informs your requirements list and considerations.
58 |
59 | ## Consider the workflow - sit in another environment
60 |
61 | For me, when moving towards a docs-as-code workflow, my eyes were opened when a developer told me he'd never want to leave his Terminal window to write docs. Think about the context switch from coding to opening a wiki page. Many developers do not see a need to open a browser window simply to log in and edit a page that they have to take time to find in the first place. You can avoid that context switching by placing the docs right in the code or in the same repository as the code. This context switch was a powerful push for me, even when pushing away from my familiar XML territory.
62 |
63 | ## Authentication and privacy needs
64 |
65 | Sometimes wikis are seen as internal-only documentation sites, which is a good use case because the wiki can be accessed only behind a firewall, for example. GitHub Pages from Github.com are publicly available when published, even when publishing from a private repository. (Updated July 2022: refer to [Changing the visibility of your GitHub Pages site](https://docs.github.com/en/enterprise-cloud@latest/pages/getting-started-with-github-pages/changing-the-visibility-of-your-github-pages-site) for information about managing access control for your project site by publishing the site publicly or privately on Enterprise Cloud GitHub.)
66 |
67 | You can implement an authentication workflow on a site uploaded to GitHub Pages, but you then need to have the web development resources to maintain the login requirement. You could use GitHub Enterprise Pages with GitHub Enterprise requiring a VPN connection to view pages. Security and openness decisions may preclude one solution or another.
68 |
69 | ## Who's reading? Who's writing?
70 |
71 | Does the wiki give you statistics you can use to figure out who knows more about a certain topic? GitHub can enable you to see which contributors are working on a particular part of the software project which can help with documentation needs. Wikis can do this too, a reader was quick to point out, but my sense is that those wikis are truly CMSes and not "quick editors."
72 |
73 | ## Automation, the game-changer for docs-as-code workflows
74 |
75 | Automated builds for review purposes are a huge gain with GitHub for documentation. While wikis have a simple save button per page, for some there is way to write scripts to automate translations or glossary re-use. Now, the more advanced and integrated wikis are certainly moving in this direction, and may sway you away from your static site generator towards a content management wiki. Wikis can be very box-like and rigid, while treating docs like code lets you automate more tasks than simply "render and publish HTML." These statements are not meant to provide final judgement on either platform.
76 |
77 | ## Information architecture, can you get what you want and release?
78 |
79 | Wikis are quite page-oriented, and in order to do releases, you might need to publish a page twice, using namespaces for example, if information affects two releases. With GitHub, you can backport a change from one release to another using branches and a similar pull request and review workflow.
80 |
81 | ## Reviews
82 |
83 | Wikis often have add-ons for review workflows, but when the heart of a wiki is quick editing, people will not easily switch to a review workflow within a wiki while in GitHub it's expected to let others review your changes before merging, or publishing in the case of a document.
84 |
85 | Sprawl can be a problem with both solutions, but the organized nature of code near documentation seems to keep the two in lock-step when the docs and code share systems such as version control and review workflows.
86 |
87 | ## Design and experiences
88 |
89 | When publishing an entire site using static sites, you get more flexibility in choosing web designs and navigation than many heavily-opinionated wiki frameworks. That said, if your web development resources know a particular wiki framework really well, they may create a nicer end-user experience in a wiki than in a highly-flexible web framework like Sphinx or Jekyll.
90 |
91 | Wikis may have a reputation built up over time with a lack of discipline in editing a page instead of starting a new page, and in gaining trusted information that can be found easily.
92 |
93 | ## Bringing it home
94 |
95 | Even as I wrote back to Gene to answer his questions, and even as I incorporated the answers into the _Docs Like Code_ book, I continue to be challenged with my answers and to reconsider some of them. Tools come and go, and our ability as professional writers remains and shines: provide the best critical analysis of the content management tools, and then write and manage the heck out of the content and the talent that creates and maintains it.
96 |
--------------------------------------------------------------------------------
/_posts/articles/2017-09-19-cisco-devnet-pubhub.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: post
3 | title: DevOps-friendly Docs Publishing for APIs
4 | excerpt: "From Mandy Whaley's presentation at All Day DevOps 2017."
5 | last_modified_at: Tue Sep 29 13:36:15 CDT 2017
6 | categories: articles
7 | author: anne_gentle
8 | tags: [documentation, docs, api, rest api, standards, openapi, raml, swagger, stripe]
9 | image:
10 | path: /images/david-huang-366041.jpg
11 | caption: "[Photo by David Huang on Unsplash](https://unsplash.com/collections/964729/milky-way-galaxy?photo=R3E2kEIC-G4)"
12 | comments: true
13 | share: true
14 | ---
15 |
16 | Here at Cisco, we have a developer program called DevNet that focuses on making Cisco APIs easier to use as well as work with developers and Cisco partners in many technology areas including IoT, Collaboration, and Software Defined Networking. The Cisco DevNet team loves working with developers, network administrators, and collaborators of all kinds. Mandy Whaley is the Director of Developer Experience for DevNet. I wanted to share details about Cisco's docs-like-code solution, PubHub, to publish both internally and externally here at Cisco. So, I used her presentation and dug into the technology as well. Here's the story of how PubHub was developed for publishing content for DevNet.
17 |
18 | > APIs need great docs. Many organizations end up with a jungle of wiki pages,
19 | > Swagger docs and API consoles, and maybe just a few secret documents trapped
20 | > in chat room somewhere... Keeping docs updated and in sync with code can be a > challenge.
21 | >
22 | > We’ve been working on a project at Cisco DevNet to help solve this problem
23 | > for engineering teams across Cisco.
24 | >
25 | > The goal is to create a forward looking developer and API doc publishing
26 | > pipeline that:
27 | >
28 | > 1. Has a developer friendly editing flow.
29 | >
30 | > 2. Accepts many API spec formats (Swagger/OpenAPI, RAML, etc).
31 | >
32 | > 3. Supports long form documentation in markdown.
33 | >
34 | > 4. Is CI/CD pipeline friendly so that code and docs stay in sync.
35 | >
36 | > 5. Flexible enough to be used by a wide scope of teams and technologies.
37 | >
38 |
39 | What did the DevNet team come up with? Let's take a look.
40 |
41 | ## What site or sites do you create from a set of Git-based repositories?
42 |
43 | The site is [developer.cisco.com](https://developer.cisco.com), and content comes from multiple repository sources, with multiple source types including markdown, RAML, and OpenAPI built with YAML or JSON.
44 |
45 | There's also [learninglabs.cisco.com](https://learninglabs.cisco.com), which is also built from repositories containing markdown for content, and JSON files for navigation elements.
46 |
47 | Plus, if a team wants to host content on their own site, the PubHub system provides links to content stored in S3 or any object storage system that can be embedded on a site. The technology that enables consistent display, styling, and seamless interaction across multiple sites and repos for all these rendered HTML snippets is a JavaScript SDK, the PubHub front-end SDK.
48 |
49 | ## What are the repositories that build the deliverables?
50 |
51 | The repositories for [developer.cisco.com](https://developer.cisco.com) content are all private and hosted on an internal Enterprise GitHub installation, moved over from an internal GitLab installation originally. There are over 450 content repos stored privately and internally, meaning that you must work at Cisco and be invited to collaborate on a particular repo.
52 |
53 | Some repositories are public, such as those for the [Learning Labs](https://learninglabs.cisco.com), so they can be browsed publically and patched by anyone on GitHub. There are nearly 200 repos for the DevNet organization itself, but those are not necessarily building learning labs, and the Learning Labs system can accept repos from any organization. There are over 300 Learning Labs available today including 25 written in Japanese.
54 |
55 | ## What factors led your team to choose a development approach for docs? Why and when was it chosen?
56 |
57 | Around 2014, some members of the DevNet team, including Mandy Whaley and API evangelist Ashley Roach, saw a need to work across all of Cisco on API and developer needs. Mandy outlines the needs the development approach met quite well in her All Day DevOps talk: developer workflows for writing and editing, friendly to continuous integration and continuous deployment systems, and flexible enough to spread across all of Cisco as a centralized supporting system for API documentation.
58 |
59 | ## What type of audience are you writing for?
60 |
61 | These sites are for all of Cisco's products, which vary from IoT (Internet of Things) to collaboration such as WebEx video conference, sophisticated phone systems with Voice Over IP (VOIP), Spark for enterprise chat, to cloud services such as Meraki, and of course our business base, networking products. The audience includes network administrators and developers who automate or manage network configuration and setup. For example, you may have seen Meraki in the small business and organizations you frequent, such as coffee shops or schools, managing the wifi for both customers and staff needs. The audience and their use cases vary and our APIs cover many use cases.
62 |
63 | ## How active is your review queue?
64 |
65 | Because the system is meant for individual teams to review their own content, the centralized team does not have to review each content change. That said, the DevNet team has tech writers help with content updates, and provides a service for on-boarding new teams who want to use PubHub.
66 |
67 | ## Do you have automation? If so, what type or tooling, and where is the automation in the workflow?
68 |
69 | Yes, absolutely as that's one of the drivers for the system, is to enable automation and integration into existing CI/CD workflows to keep in sync with code changes. The PubHub system uses Apache Kafka to manage notifications on updates for each repo and then publish them as static files. The automation for publishing is triggered when the team makes a "release" of the repository, indicating that the content is ready for public consumption.
70 |
--------------------------------------------------------------------------------
/_posts/articles/2018-01-06-video-presentations-docs-like-code.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: post
3 | title: Video Presentations about Docs Like Code
4 | excerpt: "In the last three years of Write the Docs conferences, you can learn from others experiences using docs like code techniques."
5 | last_modified_at: Sat Jan 6 10:29:44 CST 2018
6 | categories: articles
7 | author: anne_gentle
8 | tags: [writethedocs, video, conferences, GitHub, git, collaboration, transformation]
9 | image:
10 | path: /images/wtd-eur-2017.jpg
11 | caption: "[Flickr writethedocs](https://flic.kr/p/LqxXHE)"
12 | comments: false
13 | share: true
14 | youtubeIdJodie: Mzu-c-FoOdw
15 | youtubeIdPanel: Y2TGwUPb8R4
16 | youtubeIdMargJen: JvRd7MmAxPw
17 | youtubeIdRachel: dHdBsNxtKeI
18 | youtubeIdRiona: EnB8GtPuauw
19 | ---
20 |
21 | In the new year I want to keep learning more about docs like code, and I know that I've learned a lot from the Write the Docs community and presentations.
22 |
23 | Top of mind for me right now is that the 2018 conference in Portland Oregon is in May, 6-8 to be exact, and the [call for proposals closes next Wednesday](https://www.writethedocs.org/conf/portland/2018/cfp/), January 10, 2018. You can register and buy your ticket - or tickets for your whole team - [online now](https://www.writethedocs.org/conf/portland/2018/).
24 |
25 | Even when I don't make it to the conference in person, the video recordings are super helpful to learn from others. Here's a collection of the relevant talks over the years:
26 |
27 | ### 2017 US conference
28 |
29 | [Jodie Putrino](https://www.youtube.com/watch?v=Mzu-c-FoOdw) presented “Treating documentation like code: a practical account” to share her experiences at F5 Networks.
30 | {% include youtube.html id=page.youtubeIdJodie %}
31 |
32 | ### 2016 US conference
33 |
34 | [A panel](https://www.youtube.com/watch?v=Y2TGwUPb8R4) of folks from Rackspace, Microsoft, Balsamiq, and Twitter talked about how they are adopting these practices.
35 | {% include youtube.html id=page.youtubeIdPanel %}
36 |
37 | ### 2016 EU conference
38 |
39 | [Margaret Eker and Jennifer Roundeau](https://www.youtube.com/watch?v=JvRd7MmAxPw) talked about the "Missing Manual" for docs like code.
40 | {% include youtube.html id=page.youtubeIdMargJen %}
41 | [Rachel Whitten](https://www.youtube.com/watch?v=dHdBsNxtKeI) talked about docs-as-code in practice.
42 | {% include youtube.html id=page.youtubeIdRachel %}
43 |
44 | ### 2015 US conference
45 |
46 | [Riona MacNamara](https://www.youtube.com/watch?v=EnB8GtPuauw) spoke about how adopting docs like code has completely transformed how Google does documentation.
47 | {% include youtube.html id=page.youtubeIdRiona %}
48 |
49 | All this to say, the docs-like-code concepts are widely practiced in our industry, and each conference provides more inspiring examples. Perhaps you can watch these presentations and be inspired to integrate code and doc techniques.
50 |
--------------------------------------------------------------------------------
/_posts/articles/2018-04-16-practical-advice.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: post
3 | title: "Practical Advice On Publishing A Technical Book using GitHub and GitBook"
4 | excerpt: What does it take to publish a technical book using GitHub? Let's dig into tools, processes, revenue, and costs.
5 | last_modified_at: Fri Apr 20 21:01:44 CDT 2018
6 | categories: articles
7 | author: anne_gentle
8 | tags: [book, publishing, GitHub, git, gitbook, lulu, self-publishing, collaboration, design, layout]
9 | image:
10 | path: /images/designbyandren-lightbulb.jpg
11 | caption: "[Flickr designbyandren](https://flic.kr/p/cMiQAJ)"
12 | comments: false
13 | share: true
14 | ---
15 |
16 | What does it take to put together a web site, a book, an ebook, all for sale online? Let's look at costs for tools and services that make it happen.
17 |
18 | Let’s look at what you need for a book idea. You need an audience, an editor, a way to reach that audience, and a “pitch” for the book idea itself. You may chose self-publishing over pitching the book idea to a technical book publisher.
19 |
20 | In my recent experience with *Docs Like Code*, the process led me to choosing to produce the site, epub, and printed book all using tools I had prior experiences with. Let's take a look.
21 |
22 | ## Reaching out to current contacts
23 |
24 | First, I reached out to Andy Oram, a senior editor at O'Reilly who knows me from a couple of open source projects, asking if he thought O'Reilly would want a book proposal. He said he'd be happy to read what I had, but didn't see the initial concept fitting into their current catalog. Really great of him to offer to help out, and I simply thanked him and kept going with my idea.
25 |
26 | In parallel, I reached out to the publisher for my first book, *Conversation and Community*. His name is Richard Hamilton and he runs [XML Press](https://xmlpress.com). When he looked at his schedule,
27 | he couldn't read through at the draft copy for about 3 months. Well, I thought that the timing was essential, and I didn't want to wait that long, knowing both the market and my own availability.
28 |
29 | ## Finding like-minded collaborators
30 |
31 | I also reached out to Diane Fleming, now Skwish, who had been teaching writers how to use Git and GitHub for docs over the same time as I had been. Over lunch, we realized we both wanted this book to be available for the next time we teach developers and writers how to write and review docs on GitHub. Diane is a talented writer and also a super editor. The best writers re-write a lot, and I knew Diane would provide an eagle eye for both technical accuracy as well as great writing.
32 |
33 | Then, I realized I have a great friend in Kelly Holcomb, who edited my first book and I could talk her into editing this one, wahoo! Kelly also had experience in using GitHub for editing, so her contributions were super important for the final copy.
34 |
35 | One area I did skip on for this book was a professional-level index, which Kelly was able to do for a great job on for *Conversation and Community*. I haven’t missed the index yet, and for a smaller book it seems like an index could look like padding.
36 |
37 | ## Design materials and promotional work
38 |
39 | I also was able to do all the design imagery myself, including the book cover. This part was thanks to [Canva](https://www.canva.com/) and some nice templates that service has online. I used the free trial for Canva to make the book cover and stickers and t-shirt design. (Updated to add: the t-shirt store cost $300/year which was not profitable so I stopped offering t-shirts in 2019.)
40 |
41 | That said, I was not willing to take on the layout work myself. So, when [Gitbook](https://www.gitbook.com/) did not output a PDF that I considered "print-ready", I went to [Upwork](https://www.upwork.com). I wanted more fine-tuned layout and design for the print copy, including proper page breaks and nice tables. So I hired a designer with access to Indesign who could take the epub and turn it into a print book.
42 |
43 | ## Pull it together!
44 |
45 | And so, with all those bits of input from others, it created a quest to be a product manager for my own information product! I went that route, and for me, [Lulu](https://www.lulu.com/) was a tool I was already familiar with because we had done publishing with it for OpenStack.
46 |
47 | There are other publishing options - IngramSpark, Amazon, LeanPub, and I’m sure others. I did sign up and get approved for an account with IngramSpark, which is the print-on-demand service that XML Press uses.
48 |
49 | To me, after reading the [origin story for Lulu](https://www.lulu.com/about/our-story), I feel that Lulu is a bit more "open source" based than say, Amazon. I don't know much about LeanPub. Since I was using Markdown on a private GitHub repo anyway, it doesn't seem to offer more than Lulu for the marketplace reach. I'm not trying to make money at it; only trying to increase reach.
50 |
51 | Finding a freelance editor would be a huge leg up on the writing process itself, especially if you also need a bit of developmental editing for the book idea.
52 |
53 | For the print layout, I had a great experience with UpWork and was also able to hire the same person to work on the second edition. I learned from using a freelance site that I can find and manage freelancers for projects that I want to get done but don’t want to carve out time or buy tools for myself to finish them.
54 |
55 | ## List of tools and services
56 |
57 | | Tools | Site |
58 | |-----------|------------------------------------------------------------------|
59 | | Calibre | [https://www.calibre-ebook.com/](https://www.calibre-ebook.com/) |
60 | | Canva | [https://www.canva.com/](https://www.canva.com/) |
61 | | GitBook | [https://www.gitbook.com/](https://www.gitbook.com/) |
62 | | GitHub | [https://www.github.com/](https://www.github.com/) |
63 | | Lulu | [https://www.lulu.com/](https://www.lulu.com/) |
64 | | Mailchimp | [https://www.mailchimp.com/](https://www.mailchimp.com/) |
65 | | Printful | [https://www.printful.com/](https://www.printful.com/) |
66 | | Shopify | [https://www.shopify.com/](https://www.shopify.com/) |
67 | | Upwork | [https://www.upwork.com/](https://www.upwork.com/) |
68 |
69 | ## Ongoing and startup costs
70 |
71 | Here’s a high-level overview of the startup costs for creating a book like *Docs Like Code*.
72 | I calculated the starting costs for six or five months, when I needed a monthly subscription for a service.
73 |
74 | | Service | Costs |
75 | |----------------------------|---------------------|
76 | | Domain name registration | $20/year |
77 | | GitHub for Private repo | $42 ($7/month x 6) |
78 | | GitBooks for Private repo | $35 ($7/month x 5) |
79 | | GitHub Pages for website | $0 |
80 | | Canva for Work (cover art) | $0 trial |
81 | | Lulu (printed copies) | $82 for 15 printed |
82 | | Editing/Writing | $250 celebration |
83 | | Design for PDF layout | $250 |
84 | | MailChimp (ongoing) | $42 ($7/month x 6) |
85 | | Twitter ads | $25 for ads |
86 | | Stickers | $82 for 200 |
87 | | **Total startup costs** | **$828** |
88 |
89 | Based on Lulu reporting, I see the book brought in about $2500 in 12 months of the first and second edition being available. So while the startup costs are not nothing, I did see a profit from the effort. Really, though, the effort is paid off in helping others see the benefits I've observed and in sharing and learning. Let me know what you think about this method, the tools, and of course, the resulting book, *Docs Like Code*.
90 |
--------------------------------------------------------------------------------
/_posts/articles/2018-11-15-moving-agile-open-source-docs.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: post
3 | title: "Redis - Moving to Agile, Open Source Docs"
4 | excerpt: Why Redis is joining the revolution of open source docs.
5 | last_modified_at: Thu Nov 15 22:01:44 CDT 2018
6 | categories: articles
7 | author: ben_mansheim
8 | tags:
9 | image:
10 | path: /images/redislabs/writer_in_the_middle.jpg
11 | caption: "[Courtesy Redis Blog](https://redis.com/blog/moving-agile-open-source-docs/)"
12 | comments: false
13 | share: true
14 | ---
15 | "Open source” carries a lot of meaning in the world of technology these days. Twenty years after the term was coined, open source projects harness the power of voluntary contributors to produce and support software that is quickly growing in its impact on every industry, in every location.
16 |
17 | At its core, open source merely means that a product ships with the code that was written to produce it. The ability to access this source code creates the potential for modification and repackaging that is governed by a variety of open source licenses. It also can allow people to contribute modifications back into the core project, so that everyone benefits from those modifications.
18 |
19 | As a software company built on the principles of providing superior service while also promoting the common good, we at [Redis](https://www.redis.com) decided to bring this open source agility to a less known, but highly impactful, area -- Product Documentation.
20 |
21 | We feel that joining open source with documentation is a great combination to provide our community with:
22 |
23 | * Information that is always current
24 | * A platform for collaborative contributions from others
25 | * Highly accurate details from a dedicated community
26 |
27 | To find out how you can contribute, check out our [contribution guide](https://docs.redis.com/latest/contribution-guide/).
28 |
29 | So why did we decide to take the open source route for documentation? To understand, let’s look at the evolution of technical documentation over the last few years.
30 |
31 | ## The Last Revolution - Closing the delivery gap
32 |
33 | It used to be that documentation was a stumbling block in software development deadlines because all supported explanations surrounding the use of the software had to be delivered at the same time as the software itself. Worse, it started off as printed material (think user guides!) that were not only slow to create but even harder to update.
34 |
35 | Fortunately, as technology progressed, we were able to update user documentation in digital formats, saving on the “heavy” costs of printing and shipping. Writers could provide corrections, rewrites and updates to customers just as easily as engineers could provide patches to software.
36 |
37 | This revolution closed the delivery gap to enable companies to improve documentation during the lifetime of the product. However, there were still significant bottlenecks preventing customers from getting the best information possible.
38 |
39 | ## Another Pain Point - I am a bottleneck
40 |
41 | So, what traditionally stood in the way of getting the most accurate product information out there? The WRITER!
42 |
43 | The technical writer is the sole content contributor who stands between technical experts and customers to provide technical information that customers can use reliably and efficiently. Granted, a product without technical writers may be difficult to use, but the time and effort that it takes for a writer to understand the information well enough to write is another bottleneck.
44 |
45 | Since technical writers are frequently the only ones with access to the source files for published documentation, any correction, rewrite or update contribution has to be entered and produced into its final format by them.
46 |
47 | ## The Next Revolution - Open source docs
48 |
49 | Open source gives everyone some level of access to the source files of the product. In the case of Redis docs, that means putting the source files of our documentation in a publicly accessible repository. Anyone can view those source files and edit a copy of the files to suggest contributions, changing the writer from the content owner to the content editor and curator. You can even get there straight from the “Edit on GitHub” link on each page in our docs.
50 |
51 | This simple change in methodology opens ownership of the documentation’s accuracy to the technical experts within Redis, as well as our customers and partners who are experiencing the product’s behavior every single day. Add that to the immediate delivery of approved contributions at [docs.redis.com](https://docs.redis.com), and we have dramatically improved our ability to provide up-to-the-moment and accurate documentation for our customers.
52 |
53 | ## We’re Not Stopping Now
54 |
55 | Of course, this is only the beginning of the improvements we are bringing to our product documentation, but we feel that this move will be the basis for a lot of good stuff to come.
56 |
57 | So if you want to be a part of helping everyone get the most out of the fastest database in the world, don’t hesitate -- Contribute!
58 |
--------------------------------------------------------------------------------
/_posts/articles/2019-04-20-github-pages-python-sphinx.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: post
3 | title: Yes You Can Use GitHub Pages with Python Sphinx
4 | excerpt: "Learn some pro tips to build Python Sphinx developer docs to both GitHub Pages and your local system."
5 | last_modified_at: Sat Apr 20 09:43:00 CDT 2019
6 | categories: articles
7 | tags: [github, git, python, sphinx, documentation, developer, docs]
8 | image:
9 | path: /images/keyboard-mleung311.jpg
10 | caption: "[Flickr mleung311](https://flic.kr/p/fqJJbW)"
11 | comments: false
12 | share: true
13 | ---
14 |
15 | If you prefer to write in ReStructured Text instead of Markdown for your technical documentation, you're in good company. There are quite a few benefits to using Sphinx, Python, RST, and Sphinx extensions because these tools are custom-built with developer documentation in mind.
16 |
17 | Another great offering is GitHub Pages, with automatic publishing when a known branch, such as the `master` or `gh-pages` branch is updated.
18 |
19 | So, how about the best of both? Let's dive into the key configurations that enable you to publish Python Sphinx pages to GitHub Pages.
20 |
21 | ## Naming the GitHub repository can affect the resulting URL
22 |
23 | If you want a URL like `
34 |
35 | To see an example of this setup, look at the Microsoft 365 community documentation repository at [https://github.com/MicrosoftDocs/microsoft-365-community/](https://github.com/MicrosoftDocs/microsoft-365-community/). The `CODEOWNERS` file contains a team name, `@microsoftdocs/officedocs-admin`, and those team members can review and merge the list of documents in the `CODEOWNERS` file. The documents contain configuration information as well as the `CODEOWNERS` file itself.
36 |
37 | Example `CODEOWNERS` file from MicrosoftDocs:
38 | ```
39 | docfx.json @microsoftdocs/officedocs-admin
40 | .openpublishing.build.ps1 @microsoftdocs/officedocs-admin
41 | .openpublishing.publish.config.json @microsoftdocs/officedocs-admin
42 | CODEOWNERS @microsoftdocs/officedocs-admin
43 | .acrolinx-config.edn @microsoftdocs/officedocs-admin
44 | ```
45 |
46 | Think about ways you can protect your branches with a known group of reviewers. This workflow builds trust and safety while also ensuring you can move fast when needed in a larger team and repository setting.
47 |
--------------------------------------------------------------------------------
/about/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: post
3 | title: About Docs Like Code
4 | excerpt: "Brought to you by the author of the Just Write Click blog, Anne Gentle."
5 | last_modified_at: Wed Nov 23 19:25:15 CST 2016
6 | image:
7 | path: /images/robot-in-grass.jpg
8 | caption: "[Flickr, hddod By NC ND 2.0](https://www.flickr.com/photos/hddod/7229001564/)"
9 | ---
10 |
11 | Looking for a way to invigorate your documentation team and grow that team to include developers, designers, and writers of all backgrounds? Plus, how about inviting some robots into the mix for good measure? Let's treat docs like code.
12 |
13 | ## Treating docs like code is:
14 |
15 | * Collaborating with contributors efficiently by keeping docs close to code or in the same system as code, with a source file concept and an output for deliverables.
16 | * Building documentation as repeatably and consistently as possible across multiple platforms. While typically done with open source tools, the main driver is not open source but open, repeatable, consistent collaboration.
17 | * Applying software development tools and techniques to documentation about software, application programming interfaces (APIs), or other technical topics.
18 | * Learning enough about web development to be dangerous and create beautiful, modern docs.
19 | * Valuing technical accuracy and consistency.
20 | * Trusting team members to value documentation, respect end-users needs, and advocate for the best deliverables for consumers of the documentation.
21 | * Automating and integrating documentation builds so you and your teams can focus on content.
22 |
23 | ## Choose your docs-as-code adventure
24 |
25 | In a choose your own adventure series, you first pick the look for the site, then discover the developer language that pairs with the static site generator and then the CICD integration follows. We walk through setting up the development environment, and then show how to automate using docs CICD pipelines including Read the Docs, GitHub Pages, and Netlify.
26 |
27 | You may also test the docs by with Continuous Integration (CI) systems like TravisCI or CircleCI. If you need to work within existing CI systems, choose a tool that other teams use within your organization, and your choice of output is not limited by the CI system. In other words, the test frameworks in TravisCI or CircleCI do not dictate your deployment system.
28 |
29 | In the [Learn section of the site](https://docslikecode.com/learn/), there are three example documentation sites you can write and build using an SSG with CICD.
30 |
31 | Choose your adventure and start one of these sites - and learn how to do docs as code along the journey.
32 |
33 | ## Ready to learn more?
34 |
--------------------------------------------------------------------------------
/articles/index.md:
--------------------------------------------------------------------------------
1 | ---
2 | layout: categories
3 | title: Articles
4 | excerpt: "Read articles to learn more about the docs like code vision and how to try it for yourself."
5 | search: false
6 | entries_layout: grid
7 | ---
8 |
--------------------------------------------------------------------------------
/favicon.ico:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/justwriteclick/docslikecode/d9430e326fa595cd175c576e5f379f5b2bb37460/favicon.ico
--------------------------------------------------------------------------------
/favicon.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/justwriteclick/docslikecode/d9430e326fa595cd175c576e5f379f5b2bb37460/favicon.png
--------------------------------------------------------------------------------
/feed.xml:
--------------------------------------------------------------------------------
1 | ---
2 | sitemap: false
3 | ---
4 |
5 |
6 | 
