Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions _config.yml
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
# Site wide configuration

title: Write, Review, Test, Merge, Build, Deploy, Repeat. <br> Let's Treat Docs Like Code
title: Let's Treat Docs Like Code
locale: en-US
description: When you want to write more content, create accurate technical docs, iterate with collaborators, test drafts, merge, build, and deploy docs.
description: Read stories, learn through adventures, share with others.
logo: /images/treat-docs-like-code.png
#url: http://127.0.0.1:4000
url: https://www.docslikecode.com
Expand Down
3 changes: 3 additions & 0 deletions _posts/articles/2018-06-05-cloudify-dont-stop-dreaming.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ So this is the story…
The first task I received when I arrived at the company seemed simple. “Our sidebar table of contents (TOC) has a long list of top-level categories that are not well organized and confusing to our customers.” Well, sounds easy enough. To get started, we’ll make a hierarchy that simplifies those categories into 5 groups that basically match 5 types of users. Once we get that quick win we can then look at the content in the categories and combine information in the different topics to condense the content into fewer topics. I figured I could have that done in a week with a lot of buffer. My boss said, “Great!”

![Old Cloudify docs](../../images/cloudify/old-cloudify-docs.png)

([Old Cloudify Docs Site](https://docs.cloudify.co/4.2.0))

Now, here are the pitfalls that I met along the way:
Expand All @@ -47,6 +48,7 @@ After a few weeks of struggling to learn where everything was and getting nowher
Then I looked for a Hugo theme that looked good for documentation and found DocDock. It had a lot of the things that I wanted, including TOC based on directory structure , a main landing page, expanding blocks, single-sourced excerpts, and greatly improved search functionality. When I added the theme to my repo, the site built right away. Great, finally something that worked smoothly! I showed the result to my boss and we agreed that there was a lot of hope here. I told her that I think we could get a fully-functioning POC in a week. Turned out to be a little optimistic.

![Hugo Docdock theme](../../images/cloudify/hugo-docdock.png)

([DocDock Theme Site](http://docdock.netlify.com/))

Some of the challenges that I faced were:
Expand All @@ -72,6 +74,7 @@ Release day arrived. I scheduled it on a Sunday to minimize disruption, of cours
I finally merged the changes from my side-branch into the master branch and things went pretty smoothly. Some tweaks were required but nothing so bad that I needed to rollback again. Unfortunately, a few more days of struggle with redirections of old URLs using AWS S3 only brought frustration. Then, I found that I could add an alias to each page so that Hugo published HTML files at the old URL locations to redirect to the new URLs. I can safely say that was the final step that brought the project to a successful conclusion.

![New Cloudify docs](../../images/cloudify/new-cloudify-docs.png)

([New Cloudify Docs Site](https://docs.cloudify.co/))

## Success at last!
Expand Down
Binary file modified images/docs-like-code-womens-cut-tshirt.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
15 changes: 7 additions & 8 deletions index.html
Original file line number Diff line number Diff line change
Expand Up @@ -5,22 +5,21 @@
search: false
---

<img src="images/docs-like-code-book.jpg" alt="Docs Like Code Book" align="right" hspace="20" height="100" width="159">
<a href="http://www.lulu.com/spotlight/justwriteclick"><img src="images/docs-like-code-book.jpg" alt="Docs Like Code Book" align="right" hspace="20" height="100" width="159"></a>

<h1>About the book</h1>
<p>We've transformed the way teams work together on docs, and we want to talk about the best practices for writing docs using development tools and techniques.</p>
<p><a href="http://www.lulu.com/spotlight/justwriteclick" class="btn btn--light-outline btn--large"><i class='fa fa-book'></i> Buy Now</a></p>
<p><a href="http://www.lulu.com/spotlight/justwriteclick" class="btn"><i class='fa fa-book'></i> Buy Now</a></p>


{% include sign-up.html %}


<h1>Get the t-shirt!</h1>
<h2>Get the t-shirt!</h2>

<a href="https://just-write-click.myshopify.com/">Now available - Docs Like Code t-shirts</a>!

<a href="https://just-write-click.myshopify.com/"><img src="images/docs-like-code-womens-cut-tshirt.png" alt="Docs Like Code T-shirt" align="center"></a>
<a href="https://just-write-click.myshopify.com/"><img src="images/docs-like-code-womens-cut-tshirt.png" alt="Docs Like Code T-shirt" align="right"></a>

<h2>Articles</h2>
<p>Read more <a href="{{base_url}}/articles/">articles</a> on this site about
using GitHub for documentation. Let's find out the best practices and create a balance point between artisanal craft and automation efficiency.
</p>

{% include sign-up.html %}
5 changes: 1 addition & 4 deletions tshirt/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,11 @@
layout: page
title: Get the Shirt
excerpt: "Docs Like Code T-shirt, buy a shirt and wear it with pride!"
image:
path: /images/docs-like-code-womens-cut-tshirt.png
caption: "[Shopify mockup](http://just-write-click.myshopify.com/)"
comments: false
share: true
last_modified_at: Sat May 13 08:39:50 CDT 2017
---

Get <a href="http://just-write-click.myshopify.com/">t-shirts</a> now!
<a href="https://just-write-click.myshopify.com/"><img src="../../images/docs-like-code-womens-cut-tshirt.png" alt="Docs Like Code T-shirt" align="center"></a>

{% include sign-up.html %}