The hero will go through a journey to take drab README.mds into a new world allowing for flexibility and a new level of embedding for code. He will bring these learnings back to his home making all this documentation clear and executable.
this will include:
- Embedding the contents of code files into documentation (embedme)
- Enabling tab controls to allow for multiple versions of code to be contained in one set of documentation (slate)
- Embed diagramming into documentation as a living diagram not an image (lucidChart + Github)
- Automatically create issues using puzzle development (pdd)
Reid is a technical writer for a software company who knows how to make README documentation.
One day a developer rewrote all the shell scripts associated with Reids documentation into powershell and asks Reid to update all his documentation to include those scripts for windows users which could look really great as a website.
He says his README documentation is enough and has all the information need once he puts in both versions, then you just have to look for it, and he doesn't have time to learn how to make it into a website.
Another developer, Ruby, is hired at Reids company and she shows him how to use embedme to update all the script blocks in documentation to include powershell as well and automatically, which makes including the new scripts much easier using the command make embedme to simplify this task.
With all Reids new free time she shows him slate, something she worked on at her last company, which prompts him to click the link and enter a whole new world.
---> Join Reid and Ruby in the magical world in ACT 2 <-----
. . . . . . . . . . . . . . . . . . . . .
Back in the ordinary world Reid readied himself to apply what he had learned to his work with his team. He excitedly showed the senior developers how they can use lucid chart to embed diagrams into the documentation, removing the need for him to keep those up to date. He told the developers how to reference scripts and code blocks in READMEs to automatically keep script blocks up to date. He showed his team the link to the magical world, and how they can support so many different types of code and documentation styles using it. The team was excited and thought the new style was so much cleaner than their old method of just READMEs.
After they had decided to go through with using the new documentation style, the manager saw what Reid was promoting, and wasn't happy.
"Reid, I need my developers to develop features and not spend all this time messing around with documentation! That is what I pay you for!" his manager exclaimed.
"I can't do it all alone! And you can't hire another documenter so this is the only way! The team is excited to use the new tools I have shown them, and it won't be a huge commitment from them.", Reid said.
"Well Reid, what do you say you do here now if all your work is being done by the developers? You can't have other people do your job and still get paid to do it?!" his manager questioned.
Reid lowered his head and thought to himself. That is true, if they are able to keep most of the documentation up to date, and have a higher quality then what is he needed for? Did he just enable himself out of a job?
Ruby chimed in, "Reid can do development work. He has learned how to integrate these documentation tools together proving that he has the ability. With a little training and studying he can be just as productive as the other developers."
Reid's eyes widened in shock as he looked to Ruby. He couldn't really do it could he? He knew some simple commands, but could he really write code?
Another developer joined in, "Yeah that is true. Reid already knows so much about how everything works that he can pick it up really fast. He already has shown that he can learn new things, why don't we give him a shot? We can coach him through the basics."
"You all believe that by changing things up this much we can be just as productive as before? I have board members breathing down my neck to make sure our t-shirt launch is on time and I can't sacrifice any features for this 'experiment'" the manager said.
"We can do it!" Reid exclaimed, bolstered by his team's support. "I know it sounds like a risk, but I have been here a long time and have learned how things work by describing the processes. I know with my team's support I can contribute even more than I could before when I was the feature documentation bottleneck."
"What about the hat team?" The t-shirt manager said.
"I will teach them the same thing the T-shirt team learned, then they won't need me anymore and I can be fully dedicated to the t-shirt team." Reid said hopefully.
"Well that isn't my call, but I expect you to be fully productive on my team soon if you are going to be a developer." t-shirt manager said.
Reid brought his new ideas to the hat team and they were resistant at first, but found they had fewer updates since it is a more stable platform, so it wasn't a huge burdon to manage their own documentation. This let Reid be fully dedicated to learning to be a developer and focus on the t-shirt team.
Ruby and the other developers paired with Reid to help him get up to speed on programming. It took him a couple months before he was really able to be independent, but after a while he was just as productive as any other dev, and his docuemntation around changes was the most clear, making him a valuable member of the team.
The t-shirt team worked tireslessly to meet their deadline that was coming up. The team was suprised that they actually were ahead of schedule. There were plenty of things that could always be improved, but you could see the hat website up on their production like infrastructure, they just have to push the button to make it public.
The team was super excited about the progress they were able to make. The site goes live and is vastly successful. The entire company is extremely excited, and the t-shirt manager gets a promotion and praise for the great job he did by leading such a succesful team. Reid knew it wasn't the manager who made them succesful, but he knew there was no sense trying to get his team more credit.
Months later the now apparel company decided to sell pants as well, and when spinning the new team they are able to leverage a lot of the code and infrastructure from the t-shirt team due to the well documented code and infrastructure. Reid's development skills continue to increase, and he becomes a strong developer.
He is soon well respected and gets promoted to senior developer. He continues his spirit of experimentation and trying new things to great success and he helps lead his team to be the highest performing team in the company.